Shieldpay

[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/24251641-e92acdb0-8e08-4fb1-8228-d9412aa2ab47?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D24251641-e92acdb0-8e08-4fb1-8228-d9412aa2ab47%26entityType%3Dcollection%26workspaceId%3D36294760-618a-43aa-a1a7-610bbb956544#?env%5BShieldpay%20Environment%5D=W3sia2V5IjoidXJsIiwidmFsdWUiOiJodHRwczovL2FwaS5zYW5kYm94LnBhcnRuZXIuc2hpZWxkcGF5LmNvbSIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiaHR0cHM6Ly9hcGkuc2FuZGJveC5wYXJ0bmVyLnNoaWVsZHBheS5jb20iLCJzZXNzaW9uSW5kZXgiOjB9LHsia2V5IjoiYXV0aF90b2tlbiIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InRleHQiLCJzZXNzaW9uVmFsdWUiOiIiLCJzZXNzaW9uSW5kZXgiOjF9LHsia2V5IjoicG1saWJfY29kZSIsInZhbHVlIjoiKiogSW5zZXJ0IGNvZGUgZnJvbSBoZXJlOiBodHRwczovL2pvb2xmZS5naXRodWIuaW8vcG9zdG1hbi11dGlsLWxpYi9kaXN0L2J1bmRsZS5qcyAqKiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiKiogSW5zZXJ0IGNvZGUgZnJvbSBoZXJlOiBodHRwczovL2pvb2xmZS5naXRodWIuaW8vcG9zdG1hbi11dGlsLWxpYi9kaXN0L2J1bmRsZS5qcyAqKiIsInNlc3Npb25JbmRleCI6Mn0seyJrZXkiOiJwcml2YXRlX2tleSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiIiLCJzZXNzaW9uSW5kZXgiOjN9LHsia2V5Ijoib3JnYW5pemF0aW9uX2lkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6NH0seyJrZXkiOiJ1c2VyX2lkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6NX0seyJrZXkiOiJzb3VyY2VfaWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiIiwic2Vzc2lvbkluZGV4Ijo2fSx7ImtleSI6InVzZV9pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiIiLCJzZXNzaW9uSW5kZXgiOjd9LHsia2V5IjoicGF5ZWVfaWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiIiwic2Vzc2lvbkluZGV4Ijo4fV0=)

# Getting Started

The Shieldpay API is a JSON RESTful API that allows you to interact securely with the Shieldpay application.  Webhooks are used to deliver asynchronous event notifications

The information on this page is to help developers integrate with the APIs. The page is divided into 3 vertical sections:

- Left-hand side has the navigation menu and search field
- API definitions (API name, request header, parameters, body, response fields) in the middle
- On the right, one can view sample JSON responses.

## Authentication

Your authentication profile is made up of a public/private key pair, a signed certificate and an API Key. Combined, they identify your organisation and allow you to authenticate with our API.

### Mutual TLS

A Mutual TLS connection is established using your private key and the certificate that's been signed by Shieldpay's certificate authority.

To obtain a signed certificate, you will need to provide Shieldpay with a Certificate Signing Request (CSR) that contains information about your organisation. To generate your private key and CSR, see [Generate Public/Private Key Pair and CSR](#section/Getting-Started/Generate-PublicPrivate-Key-Pair-and-CSR) below.

### API Key

Your account manager will provide you with an API Key for your organisation. This will be provided at the same time your signed certificate is sent to you.

The API Key should be provided in the `Authorization` header of every API request.

```text
Authorization: Y1rXCB5XDorp0R8BI5y0D6VoPIn2L5q0zWv3
```

**You must keep your API Key secure. If someone has access to it, they can use it to make requests to the API that will authenticate as your organisation**

## Digital Signature

We use a digital signature to verify the integrity of API requests. The digital signature is generated using your [private key](#section/Getting-Started/Generate-PublicPrivate-Key-Pair-and-CSR) and is made up of the following elements:

- Request URL (without query parameters)
- [API Key](#api-key)
- [Request ID](#request-id)
- [Timestamp](#timestamp)
- Request body, exactly as it's sent in the request (including whitespace)

Generate your signature using the `RSA-SHA256` algorithm and your private key, and base64 encode the result. The digital signature should be provided in the `DigitalSignature` header of every API request. See the [examples](#section/Getting-Started/Examples) below for more help on how to generate the signature.

```text
DigitalSignature: qIwkZ9suN1vDsEjnteRVuUEdjchSRVjjwFK3D2js7Hg4j5tWEYnkfASJzoMebZu9iAu0m2T2Zi2GmolG+2u+WaYNqZDIGCWe181qdhTbHt7HqlKrZbjGWjAgztRnXQZpXhBs4ChBYwQtx7cRsx7...
```

## Generate Public/Private Key Pair and CSR

Before you generate your CSR, you will need to know your Shieldpay Organisation ID. This will be provided to you by your account manager at sign-up.

In the following examples, we use the OpenSSL library to generate the public/private key pair and CSR, but you can use any valid solution. We do not currently require the keys to be generated using a Hardware Security Module (HSM).

Generate an RSA private key.

```bash
openssl genrsa -out my-example-key.key 2048
```

Once your private key has been created, use it to generate a CSR, which will contain your public key.

```bash
openssl req -new -key my-example-key.key -out my-example-csr.csr
```

When generating the CSR you will need to provide information about your organisation. If you're using OpenSSL, after running the command above, you should see something similar to what's below.

```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 []:
```

The only requirement is that the Organization Name (O) for your certificate's subject must be your Organisation ID, which will be provided to you by your account manager at sign-up. There are currently no requirements for what the other subject values need to be. Do not set a password for your certificate.

**You must keep your private key secure. If someone has access to it, they can use it to make requests to the API that will authenticate as your organisation**

### Send Your CSR to Shieldpay

Your account manager will provide you with a secure way to send your CSR to Shieldpay. Once we receive it, we will sign the certificate and return it to you.

**You must keep your signed certificate secure. If someone has access to it, they can use it to make requests to the API that will authenticate as your organisation**

## Additional Requirements

### Request ID

All requests must include a `RequestID` header that contains a randomly generated v4 uuid. This is used for idempotency checks. The request id should be different for every request. If we receive more than one request with the same request id from your organisation within a 24 hour period, all requests after the first one will be considered a duplicate and you will receive a `409` response code.

```text
RequestID: 6e4d76af-a440-44d9-b9c1-b53c1ea3aa0e
```

### Timestamp

All requests must include a `Timestamp` header that contains an ISO 8601 timestamp in UTC. If the request timestamp is in the future, or more than 5 minutes old, the request will be considered invalid and you will receive a `401` response code.

```text
Timestamp: 2023-04-14T16:20:32.189Z
```

### Whitelist IP

All requests to our API must come from a whitelisted IP address. Your account manager will provide you with a secure way to send your IP addresses to us. Once received, we will whitelist them in our firewall.

## Examples

The code provided in these examples is solely for demonstration purposes and is not intended for production use. It has been simplified for brevity.

- [NodeJS](/examples/node.html)
- [PHP](/examples/php.html)
- [Postman](/examples/postman.html)

## Sandbox And Production

Shieldpay has two API environments: Production and Sandbox. The Sandbox environment can be used for development purposes and the requests never hit the live servers, so do not incur any risk.

- Sandbox API: [https://api.sandbox.partner.shieldpay.com](https://api.sandbox.partner.shieldpay.com)
- Production API: [https://api.partner.shieldpay.com](https://api.partner.shieldpay.com)

# Webhooks

Please provide your POST HTTPS callback URL to [Shieldpay Support](mailto:support@shieldpay.com) to register for webhooks. This feature will send the following payloads (JSON) for KYC, Project, Source and Use status updates.

##  KYC Success

Returns a collection associated to a User.

**Response**

| Response Fields | Data Type | Description
| ------------------- | ------------------- | -------------------
| type | string | Payload type. Always \"kyc\" in this case.
| user_id | string | Unique identifier for the specific User.
| address_verified | boolean | User's address True if verified else False.
| user_name | string | User's full name.
| user_email_address | string | User's email address.
| user_phone_number | string | User's phone number.

##  KYC Fail

Returns a collection associated to a User.

**Response**

| Response Fields | Data Type | Description
| ------------------- | ------------------- | -------------------
| type | string | Payload type. Always \"kyc\" in this case.
| user_id | string | Unique identifier for the specific User.
| address_verified | boolean | User's address True if verified else False.
| user_name | string | User's full name.
| user_email_address | string | User's email address.
| user_phone_number | string | User's phone number.

##  Project status update

Returns a collection associated to a Project.

**Response**

| Response Fields | Data Type | Description
| ------------------- | ------------------- | -------------------
| type | string | Payload type. Always \"project\" in this case.
| project_id | string | Unique identifier for the specific Project.
| project_status_id | int | Determines the current status of the Project. See the **project-statuses** resource for possible values.

##  Source status update

Returns a collection associated to a Source.

**Response**

| Response Fields | Data Type | Description
| ------------------- | ------------------- | -------------------
| type | string | Payload type. Always \"source\" in this case.
| source_id | string | Unique identifier for the specific Source.
| fund_status_id | int | Determines the fund status of the Source amount. See the **fund-statuses** resource for possible values.

##  Use status update

Returns a collection associated to a Use.

**Response**

| Response Fields | Data Type | Description
| ------------------- | ------------------- | -------------------
| type | string | Payload type. Always \"use\" in this case.
| use_id | string | Unique identifier for the specific Use.
| payment_status_id | int | Determines the payment status of the Use amount. See the **payment-statuses** resource for possible values.

##  Payee verified

Returns a collection associated to a Payee.

**Response**

| Response Fields | Data Type | Description
| ------------------- | ------------------- | -------------------
| claimant_id | string | Unique identifier for the Claimant.
| project_id | string | Unique identifier for the Project.
| use_id | string | Unique identifier for the specific Use.
| verify_date | datetime | A UTC datetime on that payee was verified.
| type | string | Payload type. Always \"claimant\" in this case.


Shieldpay Professional Services API

Projects

Returns a collection of all Projects associated with the API user.

Retrieve all the Project's

Add different types of Projects into the system. *check Project Types resource for more information.

Add a Project v1

Returns all details of a specific Project based on the Project ID.

Retrieve a Project

Amend a Project's details based on the Project ID.

Update a project

Returns a collection of all Transactions associated with a Project based on the Project ID.

Retrieve all Transactions

Add a User to a specific Project based on Project ID and User ID, includes setting the specific user permissions and their approval role.

Add a user

Remove a User from a specific Project using Project ID and User ID.

Remove a user

Get a collection of all Users associated with a specific Project based on the Project ID.

List all users

Request OTP to approve all the Uses based on the Project ID

Approve all the Uses associated to a Project based on the Project ID.

Upload a file to a specific project based on Project ID.

Upload a file

Add different types of Projects into the system. *check Project Types resource for more information. Use this version of the Project API for Hybrid Verify.

Add a Project v2

Users

Returns a collection of all Users associated with an Organization.

Retrieve all users

Add a new User, note that they will be associated with the current Organization using the API.

Returns a specific User based on the User ID.

Retrieve a user

Amend a User's details based on the User ID.

Update a user

Retrieve all projects associated with a user

Retrieve all transactions associated with a user

Organizations

Returns a specific Organization's details based on the organization ID.

Retrieve an organization

Amend an Organization's details based on the organization ID.

Update an organization

Returns a collection of all Users associated with a specific Organization based on the organization ID.

Retrieve all users of an organization

Returns a collection of all Projects associated with a specific Organization based on the organization ID.

Retrieve all projects of an organization

Returns a collection of all Transactions associated with a specific Organization

Retrieve all transactions of an organization

Payers

Add a payer

Fetch a Payer's details based on the Payer ID. *A full list of Payers associated with a Project can be fetched through from the Projects resource.

Retrieve a payer

Amend a specific Payer based on the Payer ID.

Update a payer

Payees v2

Create/add a new payee to a Project.

Retrieve a payee

Amend details of a specific Payee based on the Payee ID.

Update a payee

Payees v3

Approve Payee(s) associated to a Project based on the Payee ID.

Approve payee(s)

Request OTP to approve Payee(s) associated to a Project based on the Payee ID.

Request OTP PIN to approve payee(s)

Currencies

Returns a collection of all available Currencies.

Retrieve list of all currencies

Returns data for a specific Currency based on the Currency ID.

Retrieve a currency

Customer Types

Returns a collection of all available Customer Types.

Retrieve list of all customer types

Returns data for a specific Customer Type based on the Customer Type ID.

Retrieve a customer type

Project Statuses

Returns a collection of all available Project Statuses.

Retrieve list of all project statuses

Returns data for a specific Project Status based on the Project Status ID.

Retrieve a project status

Fund Statuses

Returns a collection of all available Fund Statuses.

Retrieve list of all fund statuses

Returns data for a specific Fund Status based on the Fund Status ID.

Retrieve a fund status

Project Types

Returns a collection of all available Project Types.

Retrieve list of all project types

Returns data for a specific Project Type based on the Project Type ID.

Retrieve a project type

Payment Statuses

Returns a collection of all available Payment Statuses.

Retrieve list of all payment statuses

Returns data for a specific Payment Status based on the Payment Status ID.

Retrieve a payment status

Account Holders

Returns a collection of all Account Holder Types currently set-up in the platform. e.g. Individual, Business

Retrieve list of all Account holders

Returns data for a specific Account Holder Type based on the Account Holder Type ID.

Retrieve a Account holder

Country Codes

Returns a List of all Country codes associated with the API user.

Retrieve list of all country codes

Returns data for a specific Country code based on the Country Code ID.

Retrieve a country code

Sources (TO BE DEPRECATED)

Add a source

Fetch a Source's details based on the Source ID. *A full list of Sources associated with a Project can be fetched through from the Projects resource.

Retrieve a source

Amend a specific Source based on the Source ID.

Update a source

Uses (TO BE DEPRECATED)

Add a use

Retrieve a use

Amend details of a specific Use based on the Use ID.

Update a use

Approve Use(s) associated to a Project based on the Use ID.

Approve use(s)

Request OTP to approve Use(s) associated to a Project based on the Use ID.

Request OTP PIN to approve use(s)

Default

API Facade - Prod

The Shieldpay API is a JSON RESTful API that allows you to interact securely with the Shieldpay application.  Webhooks are used to deliver asynchronous event notifications

The information on this page is to help developers integrate with the APIs. The page is divided into 3 vertical sections:

Your authentication profile is made up of a public/private key pair, a signed certificate and an API Key. Combined, they identify your organisation and allow you to authenticate with our API.

A Mutual TLS connection is established using your private key and the certificate that's been signed by Shieldpay's certificate authority.

To obtain a signed certificate, you will need to provide Shieldpay with a Certificate Signing Request (CSR) that contains information about your organisation. To generate your private key and CSR, see 

Your account manager will provide you with an API Key for your organisation. This will be provided at the same time your signed certificate is sent to you.

You must keep your API Key secure. If someone has access to it, they can use it to make requests to the API that will authenticate as your organisation

We use a digital signature to verify the integrity of API requests. The digital signature is generated using your 

 and is made up of the following elements:

 algorithm and your private key, and base64 encode the result. The digital signature should be provided in the 

 below for more help on how to generate the signature.

Before you generate your CSR, you will need to know your Shieldpay Organisation ID. This will be provided to you by your account manager at sign-up.

In the following examples, we use the OpenSSL library to generate the public/private key pair and CSR, but you can use any valid solution. We do not currently require the keys to be generated using a Hardware Security Module (HSM).

Once your private key has been created, use it to generate a CSR, which will contain your public key.

When generating the CSR you will need to provide information about your organisation. If you're using OpenSSL, after running the command above, you should see something similar to what's below.

The only requirement is that the Organization Name (O) for your certificate's subject must be your Organisation ID, which will be provided to you by your account manager at sign-up. There are currently no requirements for what the other subject values need to be. Do not set a password for your certificate.

You must keep your private key secure. If someone has access to it, they can use it to make requests to the API that will authenticate as your organisation

Your account manager will provide you with a secure way to send your CSR to Shieldpay. Once we receive it, we will sign the certificate and return it to you.

You must keep your signed certificate secure. If someone has access to it, they can use it to make requests to the API that will authenticate as your organisation

 header that contains a randomly generated v4 uuid. This is used for idempotency checks. The request id should be different for every request. If we receive more than one request with the same request id from your organisation within a 24 hour period, all requests after the first one will be considered a duplicate and you will receive a 

 header that contains an ISO 8601 timestamp in UTC. If the request timestamp is in the future, or more than 5 minutes old, the request will be considered invalid and you will receive a 

All requests to our API must come from a whitelisted IP address. Your account manager will provide you with a secure way to send your IP addresses to us. Once received, we will whitelist them in our firewall.

The code provided in these examples is solely for demonstration purposes and is not intended for production use. It has been simplified for brevity.

Shieldpay has two API environments: Production and Sandbox. The Sandbox environment can be used for development purposes and the requests never hit the live servers, so do not incur any risk.

Please provide your POST HTTPS callback URL to 

 to register for webhooks. This feature will send the following payloads (JSON) for KYC, Project, Source and Use status updates.

Returns a collection associated to a User.

Returns a collection associated to a Project.

Returns a collection associated to a Source.

Returns a collection associated to a Use.

Returns a collection associated to a Payee.

projectId

name

amount

Email address associated with the Payer details.

emailAddress

Determines the currency of the Payer amount. See the currencies resource for valid values.

currencyId

description

Determines the fund status of the Payer amount. See the fund-status resource for possible values.

fundStatusId

Determines the customer type. See the customer_type resource for options.

customerTypeId

if customer type is corporate. See the customer_type resource for options.

companyId

This specifies the API key associated with your organisation, which is provided by your designated account manager.

Authorization

A randomly generated v4 UUID used for idempotency checks. Each request should have a unique ID.

RequestID

An ISO 8601 timestamp in Coordinated Universal Time (UTC). If the request's timestamp is in the future or more than 5 minutes old, the request will be deemed invalid.

Timestamp

The DigitalSignature is generated by utilising your private key and includes the Request URL (excluding query parameters), API Key, Request ID, Timestamp, and the Request body (exactly as it is sent, including whitespace). The signature is generated using the RSA-SHA256 algorithm along with your private key and then encoded using base64.

Sections