Overview

In this guide, you will learn how to integrate with the Latitude product by connecting to REST API endpoints. An API integration allows sending payouts, canceling payouts, and getting real-time status updates.

📘

Batch file alternative

REST APIs aren't the only way to integrate with Latitude for sending business-to-consumer payouts. For more information, see our guide on the Batch File Integration and the Getting Started for a comparison of the two integration options.

1. Authentication

The Latitude API uses Bearer Authentication to authenticate API calls and keep your data and your user's data safe. When you begin the implementation, the Latitude Implementations Team will provide you with a set of client credentials (Client ID and Client Secret) as well as a Sender ID. These credentials should be stored securely in a key vault.

To retrieve a bearer token from the Latitude API, use the Get Access Token endpoint.

curl --request POST \
     --url https://sandbox-api.readyremit.com/v1/oauth/token \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --data '
{
     "client_id": "{{client_id}}",
     "client_secret": "{{client_secret}}",
     "sender_id": "{{sender_id}}",
     "audience": "https://sandbox-api.readyremit.com",
     "grant_type": "client_credentials"
}'

The audience property will change based on the environment you're connecting to.

Sandbox: https://sandbox-api.readyremit.com
Production: https://api.readyremit.com

The grant_type property will always be client_credentials.

If the payload is valid and the credentials are correct, you will receive an Status Code 200 - Success with a payload that includes the bearer token. This token will be valid for 24 hours.

{
  "access_token": "<access_token>",
  "expires_in": "<expires_in>",
  "token_type": "<token_type>"
}

You can use this token to validate any request to the Latitude API by including the value of the access_token as a bearer token in the Authorization header of a request. An example can this can be seen in Step 2 of this guide.

If the payload is invalid you will receive a Status Code 400 - Bad Request with an explanation of the error. For example, if the grant_type property is missing, the payload will be:

{
    "error": "invalid_request",
    "error_description": "Missing required parameter: grant_type"
}

If the payload is valid but the credentials are incorrect, you will receive a Status Code 401 - Unauthorized.

{
    "error": "access_denied",
    "error_description": "Unauthorized"
}

2. Create a Payout

Once you've obtained an access_token you're ready to use the Latitude API to create a Payout. A Payout represents a pending Business-to-Consumer payment that must be completed by the consumer.

To create one or more Payouts, use the Create Transfer Requests in Bulk endpoint. The payload to this endpoint is an array of Payout objects. See the Create Transfer Requests in Bulk API reference page for a list of fields.

curl --location 'https://sandbox-api.readyremit.com/transferrequests/v1/transfer-requests/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "transferRequests": [
        {
        "referenceId": "ABC123",
        "senderId": "{{sender_id}}",
        "firstName": "Jane",
        "lastName": "Smith",
        "secondLastName": "",
        "email": "[email protected]",
        "phone": "5557343414",
        "addressLine1": "100 Main St",
        "addressLine2": "Apt 03",
        "city": "Atlanta",
        "state": "GA",
        "postalCode": "30339",
        "country": "USA",
        "amount": "115.00",
        "currency": "USD",
        "quoteBy": "SEND_AMOUNT",
        "supplementalInfo1": "",
        "supplementalInfo2": "",
        "verificationCode": ""
        }
    ]
}'

Reference ID

The referenceId field represents the unique identifier of this consumer payout in your system and will be used by the Latitude team when communicating with your customer support team.

This value must be unique for every Payout. If a duplicate Reference ID is submitted, it will be rejected by the Latitude API.

Handling the response

The response from the API will be the same list of Payouts you submitted, with some additional fields populated:

• id: Unique identifier assigned to the Payout in the Latitude system (NULL if there was an error.)
• status: Current status of the Payout (for a complete list of Statuses, see the Statuses page.)
• error: Description of the problem creating the Payout (NULL if there was no error.)
• expiration: Timestamp that the Payout will expire and can no longer be collected (NULL if there was an error.)
• url: The URL to be shared with the consumer that they can use to complete the Payout and collect their payment (NULL if there was an error.)

The ID can be saved in your system and associated with the payment for use in future API calls.

Status codes

Expect to receive one of the following HTTP status codes:

400 Bad Request - Indicates there was a problem with the payload. The response body should include a description of the problem. If you are unable to self-resolve, please reach out to the Latitude technical support or implementations team.

200 Success - Indicates that the payload was accepted. NOTE: A 200 Success might not mean all the Payouts were created successfully.

Status field

To verify if each Payout was created successfully, check the status property on the returned object. If the status is INVALID it means the Payout was not created successfully and will need to be re-submitted.

Any other status besides INVALID indicates that the Payout was created successfully and will include a value in the url property that can be shared with the consumer.

3. Share the Latitude portal URL with the consumer

Once the Payout has been successfully created in the Latitude system, the consumer can collect their payment. In order to collect the payment, the consumer will need to visit the unique URL generated for their in the last step. This URL can be shared with the consumer via email, or other secure form of communication.

📘

Roadmap note

Support for Latitude initiated consumer communication is now available. To learn more visit the Latitude Email Guide.

See the Branding page for a recommended email template.

4. Check the status of a Payout

There are two ways to receive updates about the status of a Payout. It is recommended that you consume the Status Update Webhook (described in step #6 below).

For on-demand statuses, you can call the Get Transfer Request endpoint using the unique ID returned in the Create Transfer Request call.

curl --request GET \
     --url https://sandbox-api.readyremit.com/transferrequests/v1/transfer-requests/{{id}} \
     --header 'accept: application/json'
     --header 'Authorization: Bearer {{access_token}}'

For a full list of Payout statuses, see the Statuses guide.

5. Cancel a Payout

In some scenarios, a Payout will need to be canceled. This might need to happen if the payment is no longer owed to the consumer, the original payment information or amount was wrong, etc. Canceling a Payout can be done using the Cancel Transfer Request endpoint.

curl --request POST \
     --url https://sandbox-api.readyremit.com/transferrequests/v1/transfer-requests/{{id}}/cancel \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer {{access_token}}' \
     --data '
{
  "reason": "OTHER",
  "reasonDescription": "Incorrect amount"
  "
}'

The only additional piece of information needed besides the ID of the Payout is a reason and an optional reasonDescription. Possible values for the reason property are:

MAIL_CHECK - If a Payout should be canceled because the consumer will receive their payment via a mailed check. For this reason, no reasonDescription is necessary.

OTHER - For all other cancelation reasons. If the OTHER reason is used, a value in the reasonDescription field is also required.

If the Transfer Request was able to be canceled, the response will be a 200 Success. If the Transfer Request could not be canceled, the response will be a 400 Bad Request with an error payload. For example, the the Transfer Request has already been submitted the payload might be:

[
    {
        "code": "TransferRequestAlreadyProcessed",
        "message": "Transfer Request has already been processed.",
        "description": "Transfer Request has already been processed."
    }
]

6. Consume the Status Update Webhook

If you want to maintain an updated status of all active Payouts, the best way to do that would be to consume API calls from Latitude's Transfer Request Status Webhook. This webhook will make API calls to an endpoint defined on your system anytime the status of a Transfer Request changes.

Authentication

Payloads to your API will include an API key in the Authorization header of the request. This API key will be provided to you by the Latitude Integrations Team. If the API key in the request does not match the provided API key, you must return a 401 Unauthorized. No response body is required.

Payload

If the API key is valid, the request payload can be parsed. The payload will include 2 properties:

transferRequestId - The unique ID of the Payout defined by Latitude when the Payout was created.

status - The new status of the Payout (for a complete list of statuses, see the Statuses guide.)

updatedAt - The date/time the Payout status was updated in ISO 8601 format.

{
  "transferRequestId": "{{transferRequestId}}",
  "status": {
    "id": "OTHER",
    "name": "Other"
  },
  "updatedAt": "2024-03-25T21:52:53.515Z"
}