Authentication

Description

All interactions with the Send Payments API start with obtaining an Authentication Token, which is further referred to as an accessToken. You will need this to access all the Endpoints except the Authentication Endpoint itself.

To obtain an accessToken, your API will need to send a request to the Authentication Endpoint and if successfully authenticated, a successful response will be sent to you containing an accessToken which you will be able to use to sign all the subsequent requests, until the accessToken expires or you request a new one.

The accessToken holds information about which services that are available to you as an authenticated user.

Send Payments API accessTokens expire after 5 minutes. You can obtain a new accessToken before your current one expires.

How to obtain an accessToken and sign requests

First you need to obtain a Client Identifier from Send. This is an environment specific user identifier for your API.
At the same time, you will need to set up the clientSecret associated with your clientId, which is the password for your API account.

You should securely store your clientId and clientSecret and you should not share these publicly.

To obtain an accessToken and use it to sign the requests you need to send a POST /auth request. Within the request you need to provide your clientId and clientSecret.

{
  "clientId": "5e505642-9024-474d-9434-e5a44f505cc",
  "clientSecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

📘

Idempotency is not needed in POST /Auth

You do not need to include the idempotency header parameter on requests to the POST /auth endpoint.

This endpoint will always respond with a new accessToken.

In response to your request you will receive either a SUCCESS 201 response or one or the error responses (400, 401, 500) See Status Codes & Error Messages.

In case of successful Authentication you will receive back your accessToken and expiresAt date and time.

{
  "item": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "expiresAt": "2023-09-26T02:01:19.22Z"
  }
}

The accessToken is a string representing a JSON Web Tokens (JWT). JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

📘

Note the “.” separating the HEADER, PAYLOAD and SIGNATURE components of the JWT.

The accessToken youve received will remain valid until you request a new one or until the expiry time. If the accessToken expires then you'll need to repeat the authentication process. Youll need to include an accessToken on all requests to endpoints other than the POST /auth.

Now that you have an accessToken you can use this to access the endpoints offered by the Send Payments API.
The accessToken contains information about which services you can access so it must be present on all requests to endpoints that require an authenticated user.
i.e. all endpoints except the POST /auth endpoint itself.

Here's an example of a signed request to create a new Account:

curl -X 'POST' \
  'https://transactional-api.demo.sendpayments.com/v2/account/individual' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
  -H 'accept: application/json' \
  -H 'idempotency: 2a705afd-d75c-4806-ac5e-92aa18b19312' \
  -H 'Content-Type: application/json' \
  -d '
  {
  "birthDate": "2019-08-24",
  "email": "[email protected]",
  "firstName": "Kim",
  "lastName": "Doe",
  "middleName": "Alex",
  "phoneCountryCode": "61",
  "phone": 295463822,
  "physicalAddress": {
    "city": "Sydney",
    "country": "AU",
    "postcode": 2000,
    "state": "NSW",
    "addressLine1": "Harbourside Apartments",
    "addressLine2": "string",
    "streetName": "Fancy",
    "streetNumber": "1",
    "streetType": "Street",
    "unitNumber": "22"
  },
  "primaryIdentification": {
    "identityCardNumber": "123ABC2344",
    "identityCountry": "string",
    "identityExpiry": "2056-09-03T00:00:00.000Z",
    "identityNumber": "88899333AA",
    "identityState": "NSW",
    "identityType": "driver_license"
  },
  "authorisedRepresentatives": [
    {
      "email": "[email protected]",
      "firstName": "Kim",
      "middleName": "Alex",
      "lastName": "Doe",
      "phoneCountryCode": "61",
      "phone": "02 7779 7399",
      "role": "Accountant"
    }
  ],
  "termsAndConditionsAccepted": true,
  "individualIsActingAsTrustee": true,
  "trust": {
    "name": "Doe Family Trust",
    "trustBeneficiaries": [
      {
        "birthDate": "1984-09-21T00:00:00.000Z",
        "firstName": "Jay",
        "lastName": "Doe",
        "middleName": "Alex",
        "physicalAddress": {
          "city": "New York",
          "country": "string",
          "postcode": 10003,
          "state": "NY",
          "addressLine1": "The Waldorf",
          "addressLine2": "string",
          "streetName": "Nice",
          "streetNumber": 1,
          "streetType": "Street",
          "unitNumber": 33
        }
      }
    ]
  }
}

📘

Not Seeing What You're Looking For?

We are always looking to improve our API documentation to ensure Sends systems are easy to understand and quick to build against. If you're struggling to find the answer to a question we either haven't made it easy enough to find the relevant docs or we haven't had a chance to write something up for it yet.

Either way we want to hear from you!

Head over to our Discussion Board and leave us a note. We keep a close eye on this and want to ensure we make these docs as useful as they can be so will jump on any posts quickly.