We recommend that you

1. Start by reading our API documentation first (see Payment Flows)
2. Download and use our Postman collection to understand our data types and use cases (these contain sample requests)
3. Download the appropriate language SDK and call our APIs from your local developer machine
4. You can test our webhooks using the simulator
5. Once you've carried out the above then you're ready to integrate our APIs into your system(s).

This API uses the OAuth 2 Bearer token for authentication.

The bearer token is sent in the request like this:

Currently you will need to contact Visa Payments Limited ([email protected]), from there we can set you up by issuing you with a unique client_id and secret. In future, you will be able to register your details on this site and receive your client_id and secret once approved.

The Sandbox environment is a complete replica of the Visa Payments Limited production environment - it supports all of the same API endpoints. Applications must be tested against the Sandbox environment before being used in production.

Currently you will need to contact Visa Payments Limited ([email protected]), from there we can set you up by issuing you with a unique client_id and secret. In future, you will be able to register your details on this site and receive your client_id and secret once approved.

• The Sandbox contains only test data and is completely separate from your production account.
• All API endpoints have a base URL of https://api-sandbox.earthport.com instead of https://api.earthport.com
• Actual money is not sent or received as part of test transactions.
• No compliance checks are performed against the test transactions such as automated AML checks.

Warning - Real financial data should never be used in the Sandbox.

Please read the suggested Developer testing steps.

The API is only available over HTTPS - any requests made using HTTP will fail to connect.

Note: You will need to ensure you are using TLS v1.2 or higher.

Once Visa Payments Limited has issued you with your client_id and client_secret you can then use these to authenticate. Authentication will return a token which has a time to live.

You will need to use this token in each subsequent API call to be authorized.

• Step 1: Authenticate
• Step 2:  Authorization

When we make backwards-incompatible changes to the API, we will release a new version. The current version is v1.

Visa Payments Limited considers the following changes to be backwards-compatible:

• Adding new API resources.
• Adding new optional request parameters to existing API methods.
• Adding new properties to existing API responses.
• Changing the order of properties in existing API responses.
• Changing the length or format of object IDs or other opaque strings.
• Adding new even types.

Your webhook listener should gracefully handle unfamiliar event types.

All requests and responses are JSON-formatted and UTF-8 encoded.

An 'Accept' header is required for all requests, for example:

Accept: application/json

A 'Content-Type' header must be given when sending data to the API (using POST and PUT endpoints), for example:

Content-Type: application/json

For both of these headers, you must give the standard JSON MIME type (application/json).

You will receive an error (HTTP status code=415) if you attempt to make a POST/PUT request without this MIME type.

Each response has HTTP headers that provide data on where your application is at for a given rate limit.

X-Rate-Limit-Limit: the rate limit ceiling for that given request

X-Rate-Limit-Remaining: the number of requests left for the 1 minute window

X-Rate-Limit-Reset: the remaining window before the rate limit resets

When the rate limit is applied the API will return a status code of "429 Too Many Requests". In which case you should wait 60 seconds before retrying.

By default, your application can perform API calls from any IP address. By configuring whitelisted IP addresses for your application, you can control the source IP addresses for the API calls made by your application. In this case Visa Payments Limited will reject any API calls made with your application credentials from any other IP address with a status code of "401 Unauthorized".

Warning - If you misconfigure whitelisted IP addresses, your application will be broken.

Please note:

• IP addresses should use only IPv4 format e.g. 192.168.100.14
• IP ranges should use CIDR notation e.g. 192.168.100.0/24 which would include 192.168.100.0 up to 192.168.100.255

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a payment fails due to a network connection error, you can retry the request with the same merchantTransactionID to guarantee that only a single payment is created.

Rather than using a separate idempotency key, we instead require a specific field per service to be unique.

Multiple POSTs where this field contains the same value won't result in multiple resources being created. In fact, an error will be returned indicating a duplicate value.