Getting Started

## Sections
• [Getting Started](https://developers.shieldpay.com/getting-started/getting-started.md): Shieldpay's API enables you to programmatically manage your payment workflows from end to end. You can create projects, manage payers and payees, and authorise payments to disburse funds securely. This guide covers the key concepts and technical requirements to start your integration. If you need help at any point, please email our Technical Support team at integrationsupport@shieldpay.com .
• [Integration Lifecycle](https://developers.shieldpay.com/getting-started/integration-lifecycle.md): From initial planning to your first live payment, we'll guide you through four key stages. 1 Planning & Product Alignment We'll start by understanding your end-to-end business flow and customer journey. This helps us define the integration scope and project timelines together. 2 Technical Kick-Off In a technical workshop, we'll get you set up on our Sandbox environment. This includes creating your organisation, providing your Organisation ID , and exchanging the necessary certificates and API keys for you to make your first authenticated API call. 3 Integration Development You'll be assigned a dedicated Technical Support contact, and we can set up a shared Slack channel for direct access to our engineers. We're here to answer questions and provide technical guidance throughout your build. 4 Certification & Go-Live When you're ready, we will collaboratively test and validate your integration in the Sandbox. Our team will provide a set of test cases covering your specific implementation. Once certified, we'll help you switch to the Production environment, issue your live credentials, and conduct final checks. Certification can take anywhere from a single day for simple integrations to several days for more complex workflows.
• [Environments](https://developers.shieldpay.com/getting-started/api-fundamentals/api-environments.md): Shieldpay provides two distinct environments. All credentials and configurations are environment-specific. Production: https://api.partner.shieldpay.com This is the live environment for processing real transactions. Sandbox: https://api.sandbox.partner.shieldpay.com A complete testing environment that mirrors Production functionality without affecting real-world data or funds. You will be onboarded to the Sandbox first. It is best practice to maintain separate application configurations for Sandbox and Production. The Sandbox environment maintains a separate IP whitelist from the Production environment, so IP addresses will need to be whitelisted on both environments. We recommend whitelisting your Development servers against our Sandbox environment and your Production servers against our Production environment to maintain separation.
• [Authentication & Security](https://developers.shieldpay.com/getting-started/api-fundamentals/authentication-and-security.md): Our API uses a multi-layered approach to security, requiring every request to be authenticated, signed, and sent from a trusted location. Every request to our API will need to: Establish an MTLS connection. Include an API Key for authentication and authorisation. Be signed with a Digital Signature for integrity checks. Include a Timestamp and Request ID. Come from a whitelisted IP address.
  • [Authentication (mTLS & API Keys)](https://developers.shieldpay.com/getting-started/api-fundamentals/authentication-and-security/authentication-mtls-and-api-keys.md): Authentication is performed using a combination of Mutual TLS (mTLS) and an API Key. mTLS Your client and our server use certificates to verify each other's identity, establishing a secure, encrypted channel. This requires a Private Key that you generate and a Signed Certificate that we provide. Your organisation can only have one Signed Certificate issued at any given time. The certificate is used in combination with your Private Key to establish a secure, encrypted mTLS connection. If you need a new signed certificate or for any certificate lifecycle requests, contact our Technical Support team at integrationsupport@shieldpay.com . API Key A unique secret token that identifies your organisation with each request. Your organisation can have multiple API keys active at any given time. API Keys do not expire, but can be deactivated by you at any time. To register new API keys, deactivate existing ones, or for any other API Key lifecycle requests, contact our Technical Support team at integrationsupport@shieldpay.com . Your API Key is provided in the Authorization header of every request. Plain text Authorization: Y1rXCB5XDorp0R8BI5y0D6VoPIn2L5q0zWv3 Your Private Key and API Keys must be kept secret. Anyone with access to them can potentially impersonate your organisation.
  • [Obtaining Your Certificate & API Key](https://developers.shieldpay.com/getting-started/api-fundamentals/authentication-and-security/obtaining-your-certificate-and-api-key.md): To get your credentials, follow this one-time process during your Technical Kick-Off: 1 Receive your Organisation ID We will provision your organisation in our system and send you your unique Organisation ID . 2 Generate a Private Key and CSR On your infrastructure, you will generate a new Private Key and a corresponding Certificate Signing Request (CSR). The Organization Name (O) field in your CSR must be your Organisation ID . 3 Send us your CSR and IP Addresses Our Technical Support team will provide you with a secure way to send us your CSR file and the public IP addresses your requests will originate from. 4 Receive your Certificate and API Key We will sign your CSR to create your Signed Certificate, generate your first API Key, and whitelist your IP addresses. We will then securely share the certificate and API Key with you.
  • [Request Signing (Digital Signature)](https://developers.shieldpay.com/getting-started/api-fundamentals/authentication-and-security/request-signing-digital-signature.md): Every API request must include a DigitalSignature header to verify the integrity of the payload. The signature is generated using your Private Key and the RSA-SHA256 algorithm. To create the signature, you must first construct a single string by concatenating the following five components in order, with no separators: Request URL (without query parameters) API Key Request ID Timestamp Request Body (the raw, unmodified JSON string, including whitespace) For example, the string to be signed might look like this: Plain text https://api.sandbox.partner.shieldpay.com/v1/projectsAPIKEY12345abcde-1234-5678-abcd-1234567890ab2025-08-13T15:30:00Z{"projectName":"New Project"} Components should be appended to the signature string in the order listed above. There should be no white space between components. For requests that contain a body (POST, PUT, etc), the body component should exactly match the body as it appears in the request payload, including white space, etc. Once you've constructed this string, sign it using RSA-SHA256 with your Private Key and Base64-encode the result. The final signature is the value you provide in the DigitalSignature header. Plain text DigitalSignature: qIwkZ9suN1vDsEjnteRVuUEdjchSRVjjwFK3D2js7Hg4j5tWEYnkfASJzoMebZu9iAu0m2T2Zi2GmolG2uWaYNqZDIGCWe181qdhTbHt7HqlKrZbjGWjAgztRnXQZpXhBs4ChBYwQtx7cRsx7...
  • [IP Whitelisting](https://developers.shieldpay.com/getting-started/api-fundamentals/authentication-and-security/ip-whitelisting.md): All API requests must originate from a whitelisted IP address. You can have multiple IP addresses whitelisted for each environment (Sandbox and Production). To add or remove an IP address, please contact our Technical Support team at integrationsupport@shieldpay.com . Changes are typically actioned within a few hours during UK business hours but can take up to two business days.
• [Additional Request Requirements](https://developers.shieldpay.com/getting-started/api-fundamentals/additional-request-requirements.md): In addition to the security requirements, every request must include the following headers. Request ID All API requests must include a RequestID header containing a unique, randomly generated v4 UUID. This is used for idempotency. If you send a request with a RequestID that has already been processed, you will receive an HTTP 409 Conflict response. Request IDs are scoped to your Organisation when performing idempotency checks. Seperate organisations can use the same RequestID without triggering a 409 response. Plain text RequestID: 6e4d76af-a440-44d9-b9c1-b53c1ea3aa0e Timestamp All API requests must include a Timestamp header containing the current time in ISO 8601 format (UTC). Requests with a timestamp that is in the future or more than 5 minutes in the past will be rejected with an HTTP 401 Unauthorized response. Plain text Timestamp: 2025-05-24T16:20:32.189Z
• [Webhooks](https://developers.shieldpay.com/getting-started/api-fundamentals/webhooks.md): We use webhooks to send you real-time POST notifications when events occur in our platform. We will send all events as a JSON payload to a single HTTPS endpoint that you provide. To configure or update your webhook endpoint, please contact our Technical Support team at integrationsupport@shieldpay.com . Responding to a Webhook To acknowledge successful receipt of a webhook, your endpoint must return an HTTP 200 OK status code. Any other response, including a timeout, will be treated as a delivery failure. Failed Deliveries If a webhook delivery fails, we will retry sending it with a 5-minute interval between attempts. We will continue to retry for 24 hours. After this period, we will stop all attempts for that specific event. Available Webhooks The type property in the JSON payload identifies the event. The following webhooks are available: KYC Success KYC Fail Project status update Source status update Use status update Payee verified See our API Reference for full details on each webhook.
• [Generating a Private Key and CSR](https://developers.shieldpay.com/getting-started/examples/generating-a-private-key-and-csr.md): This example uses the openssl command-line tool to generate a private key and CSR as discussed in the Authentication & Security section. We do not require the keys to be generated using a Hardware Security Module. 1. Generate a 2048-bit RSA Private Key: Bash openssl genrsa -out my-private-key.key 2048 2. Generate the CSR using your Private Key: Plain text openssl req -new -key my-private-key.key -out my-csr.csr When prompted, you must enter your details. The only strict requirement is that the Organization Name (O) must exactly match the Organisation ID provided by Shieldpay. Do not set a challenge password. Bash You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. Country Name (2 letter code) []:GB State or Province Name (full name) []:London Locality Name (eg, city) []:London Organization Name (eg, company) []:c9644206-dfc7-4c07-b117-f03d3c22bd93 Organizational Unit Name (eg, section) []:Example Company Common Name (eg, fully qualified host name) []:example-company.com Email Address []:user@example-company.com Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: