Authentication

Note! Instead of implementing authentication on your own please try using our SDKs available in multiple frameworks and languages which support our authentication mechanism out of the box

Authentication with the TransferZero API relies on correctly setting the headers on each request with the following data:

  • Accept and Content-Type should be “application/json”
  • Authorization-Key is your application”s API key, which can be received from the TransferZero developer portal
  • Authorization-Nonce is a string, which must be unique per request - generating a new GUID for every request is the preferred approach
  • Authorization-Signature is a HMAC-SHA512 digest of the nonce, request method, URL, and a SHA512 hash of the request body - you will need your API Secret, also available on the developer portal, to sign

You will also need

  • your API Secret, obtainable from the developer portal
  • the request body - this should be a JSON string
  • the full request URL, including protocol, host, port and query parameters

Example data

For the following example, we will assume you are using the following details to create a Personal Sender:

  • API Key: YOUR_API_KEY
  • API Secret: YOUR_API_SECRET
  • Nonce: 00c6a48a-ccb8-4653-a0c8-de7c1ab67529
  • Request Body:
{
  "sender": {
    "country": "UG",
    "phone_country": "UG",
    "phone_number": "752403639",
    "email": "email@domain.com",
    "first_name": "Example",
    "last_name": "User",
    "city": "Kampala",
    "street": "Somewhere 17-3",
    "postal_code": "798983",
    "birth_date": "1970-01-01",
    "documents": [
      {
        "upload": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAACXBIWXMAAAsT\nAAALEwEAmpwYAAAAB3RJTUUH4gEeCTEzbKJEHgAAAB1pVFh0Q29tbWVudAAA\nAAAAQ3JlYXRlZCB3aXRoIEdJTVBkLmUHAAAADElEQVQI12P4z8AAAAMBAQAY\n3Y2wAAAAAElFTkSuQmCC",
        "upload_file_name": "passport.png",
        "metadata": { "meta": "data" }
      }
    ],
    "ip": "127.0.0.1",
    "external_id": "76f69f5e-912f-43e5-bf3a-9081dbc476f4",
    "metadata": { "meta": "data" }
  }
}
  • A POST request to https://api-sandbox.transferzero.com/v1/senders

Building the signature

The string to sign is generated by concatenating request-specific strings together, joined with an ampersand (&):

  • the Authorization-Nonce value
  • the HTTP verb, in uppercase
    • GET
    • POST
    • PUT
    • PATCH
    • DELETE
  • the full request URL, including protocol, host, port, query parameters and anchors
  • a SHA512 hex digest of the request body”s JSON
    • For the example data above, this will be 947148915d2982f7897ab187fd851e854265883109935e5e8c7ba662232b2de15e92a298067687b5402319f0efebf0561d37fc4e73460c408f91c7e25bb66ae0
    • For GET and DELETE requests without a JSON body this should be the SHA512 hash for the empty string: cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
  • Please note that, depending on the language, characters in the JSON may be escaped differently and your result might be different from this - see the code example for your specific language for individual implementations.

For the example values above, this results in the following string to sign:

  • 00c6a48a-ccb8-4653-a0c8-de7c1ab67529&POST&https://api-sandbox.transferzero.com/v1/senders&947148915d2982f7897ab187fd851e854265883109935e5e8c7ba662232b2de15e92a298067687b5402319f0efebf0561d37fc4e73460c408f91c7e25bb66ae0

This string to sign is encrypted with the SHA512 algorithm and your API Secret, with the resulting value:

  • fc44e638c823b660e41f30ba78abe0e04f0dfc6b365e4a7129e44a181530146e4b777940fe8948af6fee5133b7f85d46a3cdcab449b9559617e60e593b73853c

This is passed as the Authorization-Signature header for sending the request.

Full sample header

Accept: application/json
Content-Type: application/json
Authorization-Key: YOUR_API_KEY
Authorization-Nonce: 00c6a48a-ccb8-4653-a0c8-de7c1ab67529
Authorization-Signature: eb36a61a75a7d78d16a774811122b3bbefd9fd3dfba28ffcb94b39e2c2d857cb6b22d77bb520762c813fe1a991e24862c42027c8b15b11553c03d662ed7d11f1

Complete code examples

Please check our SDKs on how thhey implement thhe authentication mechanism

API Environments

  • For testing, use https://api-sandbox.transferzero.com
  • For production, use https://api.transferzero.com

You will need a valid API Key and API Secret for each environment, obtainable in the TransferZero developer portal once your application has been approved.


Improve this page