# 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](doc:batch-file-integration-guide) and the [Getting Started](ref: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](ref:getaccesstoken) endpoint. ```curl curl --request POST \ --url https://sandbox-api.readyremit.com/v2/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.* ```json { "access_token": "", "expires_in": "", "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: ```json { "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`. ```json { "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](ref:createtransferrequestbulk) endpoint. The payload to this endpoint is an array of Payout objects. See the [Create Transfer Requests in Bulk](ref:createtransferrequestbulk) API reference page for a list of fields. ```curl curl --location 'https://sandbox-api.readyremit.com/v2/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": "jsmith@example.com", "phone": "5557343414", "addressLine1": "100 Main St", "addressLine2": "Apt 03", "city": "Atlanta", "state": "GA", "postalCode": "30339", "countryCode": "USA", "amount": "115.00", "currencyCode": "USD", "quoteBy": "SEND_AMOUNT", "supplementalInfo1": "", "supplementalInfo2": "", "verificationCode": "", "supplementalInfo3": "", "supplementalInfo4": "", } ] }' ``` ## 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](doc: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.](https://developer.latitude.brightwell.com/docs/email) See the [Branding](doc:transfer-request-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](ref:gettransferrequest) endpoint using the unique ID returned in the [Create Transfer Request](ref:createtransferrequest) call. ```curl curl --request GET \ --url https://sandbox-api.readyremit.com/v2/transfer-requests/{{id}} \ --header 'accept: application/json' --header 'Authorization: Bearer {{access_token}}' ``` For a full list of Payout statuses, see the [Statuses](doc: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](ref:canceltransferrequest) endpoint. ```curl curl --request POST \ --url https://sandbox-api.readyremit.com/v2/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: ```json [ { "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](ref:transferrequeststatuswebhook). 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 webhook API can include an API key in the `Authorization` header of the request. This API key from your system will need to be provided to the Latitude Integrations Team. If the API key in the request Latitude sends does not match the API key you provided, 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](doc:statuses) guide.) `updatedAt` - The date/time the Payout status was updated in ISO 8601 format. ```json { "transferRequestId": "{{transferRequestId}}", "status": { "id": "OTHER", "name": "Other" }, "updatedAt": "2024-03-25T21:52:53.515Z" } ```