Corpay

2026

<Divider />

### Release Date: April 20, 2026

#### Update: Multi-Currency Account (MCA) Nickname

The maximum length for the MCA nickname has been increased from 30 to 50 characters. All other validations remain unchanged. For more information, see [Assign/Edit MCA Nickname](https://developer.crossborder.corpay.com/apidocscrossborder/settlement-accounts/manage-multi-currency-accounts-nickname/assign-edit-multi-currency-account-nickname).

<Divider />

### Release Date: April 3, 2026

#### Update: Client Onboarding and Create/Edit Bene API

*   **Client Onboarding API** now supports a new Boolean parameter, `DirectDebitAuthorization`. When left blank, the value defaults to `false`. For more information, see [Client Onboarding](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client/onboarding-new).
    
*   **Nonprofit Organization** is now available as a beneficiary classification when creating beneficiaries. For more information, see [Create/Edit Bene](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/create-edit-bene).

April

<Divider />

### Release Date: March 20, 2026

#### New: Subscribe to new Payment Webhooks Events

We’ve expanded Webhooks to support new payment event types. Users can now subscribe to receive real-time notifications for the following events:

*   Corpay cancels a payment.
    
*   A client cancels a payment.
    
*   Payment is returned to the client.
    

For more information, see [Webhooks](https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events).

<Divider />

### Release Date: March 9, 2026

#### **Enhanced Validations for Canadian Bank Account Numbers**

*   Effective **Monday, March 09, 2026**, the system will enforce the length of Canadian bank account numbers based on the bank’s routing code and payment method (Wire or EFT) used when creating or editing a bene template. If the account number length is invalid, the [Create/Edit Bene API](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/create-edit-bene) response will return a regex error. An optional `routingCode` parameter has been added to the [Get Beneficiary Rules](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/beneficiary-rules) endpoint to return the required account number length based on the provided routing code.
    

#### **New Indicative Rate Endpoint Introduced**

*   We added a new `GET Indicative Rates` endpoint to return an indicative rate request for a Spot transaction. For more information, see [GET Indicative Rates](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/indicative-rate).
    

#### **Client Onboarding Request Update**

*   The `BusinessConfirmationEmail2` parameter in the **Client Onboarding** request is now **required.** If no alternate email address is available, users must enter their primary registered email address. For more information, see [Client Onboarding](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client/onboarding-new).

March

<Divider />

### **Release Date: January 9, 2026**

#### **Update: Client Onboarding API**

The Onboarding API email field parameters now support email addresses with domain suffixes exceeding three characters (e.g., support@enterprise.cloud). Previously, only three-character extensions were accepted. See [Client Onboarding](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding).

January

<Divider />

Key 2025 feature releases and improvements.

2025

<Divider />

### Release Date: October 31, 2025

#### Update: Client Onboarding API

We made the following enhancements to the Client Onboarding API:

*   Added new fields to support regional onboarding (CA, US, UK, AU, NZ, SG, EEA). See [POST Client Onboarding](https://developer.crossborder.corpay.com/managepricing/client-onboarding-1/onboard-client/onboarding-new).
    
*   Introduced new picklist types for validating onboarding request values. See [GET Onboarding Picklists](https://ttps://developer.crossborder.corpay.com/managepricing/client-onboarding-1/reference-data/new-onboarding-picklists).
    

See [Client Onboarding](https://developer.crossborder.corpay.com/managepricing/client-onboarding-1).

October

<Divider />

### Release Date: September 5, 2025

#### Update: Purpose of Payment API

The [GET Purpose of Payment](https://developer.crossborder.corpay.com/managepricing/beneficiary-workflow/beneficiary-help/purpose-of-payment) endpoint now supports three additional values:

*   Royalties
    
*   Reimbursement payment
    
*   Winnings
    

These values are returned in the standard purpose of payment response. Call the API to confirm the allowed POP values for unique currency and payment method combinations.

September

August

<Divider />

### Release Date: July 31, 2025

#### New API Endpoints: Manage Multi-Currency Account Nickname

You can now assign, update, and reset the nickname for your Multi-Currency Accounts via the API endpoints available [here](https://developer.crossborder.corpay.com/apidocscrossborder/settlement-accounts/manage-multi-currency-accounts-nickname).

<Divider />

### Release Date: July 25, 2025

#### Updated: Incoming Funds Details API

As part of our ongoing improvements to Corpay's API suite, we have renamed the Incoming Deals API endpoint from: `incoming-funds-details/{dealNumber}` to `incoming-funds/{ordNum}`. There are no changes to the returned response.

**Note**: The old endpoint will be deprecated and made obsolete on **Friday, August 15, 2025**. If you have downloaded our API collection into your Postman instance or codebase, please ensure it is updated.

See [GET: Incoming Funds Details](https://developer.crossborder.corpay.com/apidocscrossborder/settlement-accounts/incoming-funds-details)

July

<Divider />

### Release Date: June 27, 2025

#### New: Subscribe to Incoming Funds Webhooks Events

We’ve enhanced Webhooks to include new event types. Users can now subscribe to receive real-time notifications when:

*   Incoming funds are applied to their Multi-Currency Account.
    
*   A payment is held at Corpay.
    

See [Webhooks](https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events/incoming-funds-events).

#### New API: Incoming Funds Details

We've introduced a new API endpoint - [GET: Incoming Funds Details](https://developer.crossborder.corpay.com/apidocscrossborder/settlement-accounts/incoming-funds-details) that provides users with complete details of the incoming funds received into their MCA.

#### Update: Onboarding Purpose of Transactions Picklist

We've updated the [Onboarding Purpose of Transactions Picklist API](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/reference-data/onboarding-picklists) to include additional values. Partners can now include specific Purpose of Transaction details to support compliance requirements.

<Divider />

### Release Date: June 13, 2025

#### Update: Payment Channel Information API

Based on the payment method used, the [Payment Channel Information API](https://developer.crossborder.corpay.com/apidocscrossborder/payment-tracking/payment-channel-information) will now return either **SWIFT MT103** or **SWIFT MX Pacs.008.001.08** raw details in the response payload. The corresponding status in the response will be displayed as `MT103` or `Pacs.008.001.08`. For more information, read [here](https://cb.corpay.com/api-resources-documentation/#coming-change).

June

<Divider />

### **Release Date: April 25, 2025**

#### **Update: Beneficiary API**

The `defaultInternalComment` field, previously used in the [Create/Edit Bene API](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/create-edit-bene) to enter For Further Credit (FFC) details, has now been renamed to `furtherCreditDetails` to provide a more intuitive and descriptive label. The [Beneficiary Validation](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-help/beneficiary-validation) and the [Get Beneficiary Rules](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/beneficiary-rules) endpoints will also reflect this update.

**Note**: The old field name is no longer supported. If the old field name is used, the API will return a `200 success` response, however, the FFC information will not be saved for that beneficiary. To ensure FFC details are saved correctly, partners must use the new field name `furtherCreditDetails`.

<Divider />

### **Release Date: April 7, 2025**

#### **Beneficiary Region and Postal Code Enforcement**

To comply with updated **FINTRAC** and related regulatory requirements, users are now required to **enter valid region and postal code information for bank and beneficiary addresses in payments made to the United States and Canada.** This update is enforced when creating or editing beneficiary information on Corpay Cross-Border via Beneficiary Templates, File Upload, or API. When using the [POST Create/Edit Bene](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/create-edit-bene) API, entering an invalid region or postal code for beneficiaries/bank addresses in the US and CA will return a `400 Bad Request` error. For more information, read [here](https://cross-border.corpay.com/api-resources-documentation/#lp-pom-block-959).

Please refer to the [GET Region](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-help/regions) API to retrieve accepted region values for US and CA beneficiary/bank addresses, and the [GET Beneficiary Rules](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/beneficiary-rules) API for valid Reg-Ex for US and CA address zip codes.

<Divider />

### **Release Date: March 7, 2025**

#### **Update: Beneficiary API**

We added an optional `defaultInternalComment` field to [Create/Edit](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/create-edit-bene) and [Beneficiary Validation](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-help/beneficiary-validation) endpoints, enabling you to enter **For Further Credit (FFC)** information details. This field has a character limit of 50, and standard regex validations will apply. This field allows you to enter the details of the recipient who will receive the funds. For example, “FFC Tom Roe 000304756”.

<Divider />

Key 2024 feature releases and improvements.

2024

November

<Divider />

### **Release Date: October 2, 2024**

#### **New API: Validate Beneficiary**

*   In response to feedback from our partners, we’ve introduced a dedicated beneficiary validation API endpoint, which allows our partners to validate their beneficiary details without creating a template. Previously, partners could only validate beneficiary data using the `POST Create/Edit Bene` endpoint. See [Beneficiary Validation](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-help/beneficiary-validation).
    

#### **Update: Partner-level Token Login**

*   If you have downloaded our API collection to your instance and are currently passing the `CMG-AccessToken:toBeDiscontinued` in the `POST` [Partner-level Token Login](https://developer.crossborder.corpay.com/apidocscrossborder/2-token-auth/partner-level-token-login) header, **please ensure it is removed**. This token has been identified as a potential cause of recent timeout errors during API authentication and is no longer required to be included in the header.

<Divider />

### **Release Date: September 13, 2024**

*   To comply with **Fintrac** and other regulatory requirements, PO Box addresses and similar variations are now restricted in the address fields when creating or editing beneficiary information on Corpay Cross-Border through the API and UI. When using the `POST` [Create/Edit Bene](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/create-edit-bene) API, entering a PO Box address in the beneficiary address fields will return a `REGEX_MISMATCH` error. This restriction currently applies to **Australia**, **Canada**, and **Mexico** and is also reflected in the `GET` [Beneficiary Rules](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/beneficiary-rules) endpoint. This update ensures that a complete physical address is provided, as required by regulatory standards.

<Divider />

### **Release Date: August 16, 2024**

*   We updated the [Mass Payments Quote](https://developer.crossborder.corpay.com/apidocscrossborder/mass-payments/multiple-payments) endpoint to return the `trackerId` in the response. With this update, our partners can retrieve the `trackerId` in the Mass Payment workflow immediately and avoid subsequent follow-up API requests to retrieve the payment tracker IDs.
    

### **Release Date: August 02, 2024**

*   We updated the [Partner](https://developer.crossborder.corpay.com/apidocscrossborder/2-token-auth/partner-level-token-login) and [Client](https://developer.crossborder.corpay.com/apidocscrossborder/2-token-auth/client-level-token-login) level token endpoints to return a 400 HTTPS error for null or invalid form data, instead of the previously returned 500 error. This update improves error handling.

<Divider />

Key 2023 feature releases and improvements.

2023

<Divider />

### **Release Date: October 02,2023**

*   Added new **Push Notifications via Webhooks** to allow our Partners to receive real-time notifications on events that occur within their client account and eliminates the need to regularly poll the APIs to know if there is a new update. Webhooks utilize an event-driven approach to promptly send a notification when the subscribed event occurs.
    
*   The Push Notifications are currently available for **Payment** and **Client Onboarding** events. For more information, see [Webhooks](https://developer.crossborder.corpay.com/apidocscrossborder/webhooks).

<Divider />

### **Update Date: August 26,2023**

*   Corpay’s `POST Accept Terms` API endpoint is **deprecated** as of **August 26th, 2023**. To streamline our Forward workflow and reduce the number of endpoints that need to be called to successfully complete a Forward order, the `POST Accept Terms API` endpoint for the v1.8 suite is made obsolete as of the advised date. Partner’s are no longer required to send an ‘Accept Terms’ API request and instead, will complete their Forward booking with the existing `POST` [Complete Order](https://developer.crossborder.corpay.com/apidocscrossborder/forwards-and-drawdowns/forwards/3-complete-order) API endpoint.

<Divider />

### **Release Date: May 26,2023**

*   Added new authentication API to allow partners to securely access the **Secret Keys** for a newly onboarded client. This API will return an encrypted response containing the `ClientCode`, `AuthSecret`, and `UserNames` linked to the onboarded client. For more information, see `GET` [AuthSecret Keys.](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client/authsecret-keys)

<Divider />

### **Release Date: March 31,2023**

*   Added new pickListType `**NatureOfBusiness**` to the client onboarding picklists API. This `pickListType` will return a predefined list of nature of business values and further expedite the client onboarding process. For more information, see [Onboarding Picklists](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/reference-data/onboarding-picklists). **Note**: This list returns possible values that you can pass in the `NatureOfBusiness` field. You can enter any valid string value for this field.

<Divider />

### **Release Date: February 20,2023**

*   Added new [Onboarding endpoints](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding) to allow our Partners to submit a corporate client onboarding request. On successful submission of the request a unique `clientOnboardingId`is returned. They can then submit the required verification documents via the [Submit Onboarding request](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client/submit-onboarding-files) to complete the onboarding process for that client.

February

<Divider />

### Release Date: January 16, 2023

*   Added new [Payment Tracking](https://developer.crossborder.corpay.com/apidocscrossborder/payment-tracking/payment-tracking-1) endpoints to allow our Partners to trace the details and status of their payments. This feature is available only for SWIFT Payments - Wires. EFT/iACH payments are currently not supported. For more information, see `GET` [Payment Tracking.](https://developer.crossborder.corpay.com/apidocscrossborder/payment-tracking/payment-tracking-1)
    
*   Added a new field `trackerId` in the `POST Instruct Deal` and `GET Lookup Orders` response. This field will return the unique trackerId for a specific payment that can be used to trace the payment details and status. For more information, see POST [Instruct Deal](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/3-instruct-deal) and GET [Lookup Orders.](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/lookup-orders)

Corpay Cross-Border API Documentation v1.8
------------------------------------------

Corpay Cross-Border API uses HATEOAS (Hypertext As The Engine Of Application State) framework. This means every response not only provides the requested data but also includes relevant links. This provides a link on the current resource as well as all actions that can be taken from there.

Response to APIs, once authenticated, are displayed in the following model, where content and errors are provided in the appropriate lists. Links always contain a `SELF` link to the current endpoint, and any additional links, depending on the state of the resource. For example, a beneficiary object can be viewed and modified.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "content": {},</CodeLine>
  <CodeLine>    "errors": [],</CodeLine>
  <CodeLine>    "links": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>            "rel": "self",</CodeLine>
  <CodeLine>            "uri":   "https://crossborder.corpay.com/api/{{endpoint}}",</CodeLine>
  <CodeLine>            "method": {POST GET or PUT}</CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>    ]</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Introduction

Stay informed about our upcoming API changes and enhancements. We’ll announce these updates as they become available. If you have any questions, please contact your Corpay representative.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Estimated release timelines shared here are subject to change. We’ll keep you informed as we progress.</p>
</Callout>

### IP Whitelisting

**ETA: Q1 2026**

We are enhancing IP Whitelisting to improve security, flexibility, and performance across our API services.

**Key updates include**:

*   Whitelisting at both **client** and **partner** levels
    
*   Support for **IPv4**, **IPv6**, and **valid CIDR** **ranges** (for example, 192.0.2.0/24)
    
*   Removal of SQL LIKE syntax (wildcards such as % will no longer be supported)
    
*   **Improved access control** with cached authentication for faster performance
    

<Divider />

### Confirmation of Payee (CoP) and Verification of Payee (VoP)

**ETA: Q1 2026**

UK and EU payment regulatory bodies have introduced new name-checking protocols requiring banks, financial institutions, and payment service providers like Corpay to validate that payee details are correct and exactly match the associated bank account information. On **Corpay's internal workflow**, we have now enabled:

*   **UK’s Confirmation of Payee (CoP) protocol** for all incoming and outgoing GBP payments made via FPS, Bacs, and CHAPS.
    
*   **EU’s Verification of Payee (VoP) protocol** for all incoming and outgoing EUR payments made via SEPA Credit Transfer (CT) or SEPA Instant eligible BICs (for clients whose payment accounts are governed under our Ireland entity and its branches).
    

We are now **integrating CoP and VoP protocols into our REST API workflows.** Key updates include:

*   Migration to updated versions of our existing beneficiary creation endpoints.
    
*   Introduce new verification endpoints.
    

We'll keep you informed about the new endpoints and sample responses as we roll out the updates.

<Callout attributes='{"isFitToPage":true,"dataType":"error","style":{"width":"100%","minWidth":"100%"}}'>
  <p>CoP and VoP are regulatory mandates, not optional services. These checks are enforced at the regulatory level, and no exceptions are permitted. Please direct any questions to your Corpay representative.</p>
</Callout>

<Divider />

### Beneficiary Rules (Template Guide) Endpoint Update

**ETA: Q2 2026**

An updated version of the endpoint will be released. Key updates include:

*   Introduce new endpoints - `api/template-guide-rules` and `api/{clientCode}/{clientDivisionId}/template-guide-rules`
    
*   The API response will now return a list of accepted region values based on the specified `destinationCountry` and `bankCountry` parameters, ensuring compliance when creating or editing beneficiaries via the .
    
*   A new optional `routingCode` parameter will support accurate beneficiary rule retrieval for **CAD (Canada)**, addressing issues caused by varying account number digit lengths across Canadian banks and institutions.
    

We'll keep you informed about the new endpoints and sample responses as we roll out the updates.

<Divider />

### Multi-Currency Accounts (MCA) Reporting Enhancements

**ETA: Q2 2026**

To improve our MCA reporting, we'll introduce **new bank-style statements** via an **MCA Statement endpoint**, which will eventually replace the existing endpoint. Both endpoints will run in parallel during the transition period to support integration updates. We'll keep you informed about the detailed specifications, sample responses, and API deprecation timelines as we roll out the updates.

<Accordion attributes='{"style":{"width":"100%"}}'>
<AccordionItem title="Archive - 2025 Upcoming Updates" iconUrl=""><p><strong class="slate-bold">ETA: Currently in progress and expected to be available soon.</strong></p>
<p>As part of Corpay’s ongoing investment in payment modernization and compliance, we’re introducing ISO 20022-aligned enhancements to both our UI and API, enabling richer, standardized data formats. The <a href="" target="_self">Payment Tracking endpoints</a> will now return either the <strong class="slate-bold">SWIFT MT103</strong> or the <strong class="slate-bold">ISO equivalent MX messaging</strong>. Updated API docs with example responses will be published soon.</p>
<p><span style="color:rgb(56, 118, 29)"><strong class="slate-bold">Now Available</strong></span><span style="color:rgb(76, 17, 48)"><strong class="slate-bold"> </strong></span><strong class="slate-bold">- Released on: June 13, 2025. Read </strong><a href="" target="_self">here</a><strong class="slate-bold">.</strong></p>
<p><strong class="slate-bold">ETA</strong>: <strong class="slate-bold">Deployment planned for the week of August 25, 2025.</strong></p>
<p>As part of additional regulatory and banking requirements, <strong class="slate-bold">a valid POP will be mandatory when instructing payments</strong>. A Corpay accepted POP value must be entered in the <span style="background-color:rgba(35, 44, 64, 0.02);color:rgb(32, 32, 32)"><code class="slate-code">purposeOfPayment</code></span> request field when submitting a payment via the following endpoints:</p>
<ul class="slate-ul "><li class="slate-li "><div style="position:relative">POST Instruct Deal</div></li><li class="slate-li "><div style="position:relative">POST Multiple Payments</div></li><li class="slate-li "><div style="position:relative">POST Book Drawdown</div></li></ul>
<p><span style="color:rgb(56, 118, 29)"><strong class="slate-bold">Now Available</strong></span><span style="color:rgb(76, 17, 48)"><strong class="slate-bold"> </strong></span><strong class="slate-bold">- Released on: August 25, 2025</strong>. <strong class="slate-bold">Read </strong><a href="" target="_self">here</a><strong class="slate-bold">.</strong></p>
<p><strong class="slate-bold">ETA: Deployment planned for the week of August 25, 2025</strong><span style="color:rgb(0, 0, 0)">.</span></p>
<p>To maintain consistency with the Corpay Cross-Border platform, <strong class="slate-bold">editing the currency field on existing beneficiary templates via the API will be restricted</strong>. After this restriction is enforced, to change a beneficiary’s currency, a new template must be created via the API.</p>
<p><span style="color:rgb(56, 118, 29)"><strong class="slate-bold">Now Available</strong></span><span style="color:rgb(76, 17, 48)"><strong class="slate-bold"> </strong></span><strong class="slate-bold">- Released on: August 25, 2025.</strong> <strong class="slate-bold">Read </strong><a href="" target="_self">here</a><strong class="slate-bold">.</strong></p>
<p><strong class="slate-bold">ETA: Rollout planned for the end of Q2 2025. We’ll keep you informed as we progress.</strong></p>
<p>As part of our product development roadmap, we are introducing two new <a href="" target="_self">webhook</a> subscription types:</p>
<ul class="slate-ul "><li class="slate-li "><div style="position:relative">Incoming Fund Notifications:</div></li><li class="slate-li "><div style="position:relative">Payments on Hold</div></li></ul>
<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"style":{"width":"100%"},"width":"100%","minWidth":"100%"}}'>
  <p>If you’d like to be one of our pilot clients and gain early access to these webhook features, please contact your Corpay Account Manager.</p>
</Callout>

<p><span style="color:rgb(56, 118, 29)"><strong class="slate-bold">Now Available</strong></span><span style="color:rgb(76, 17, 48)"><strong class="slate-bold"> </strong></span><strong class="slate-bold">- Released on: June 27, 2025.</strong> <strong class="slate-bold">Read </strong><a href="" target="_self">here</a><strong class="slate-bold">.</strong></p>
<p><strong class="slate-bold">ETA: To be announced. We’ll keep you informed as we progress.</strong></p>
<p>We’re enhancing our <a href="" target="_self">Onboarding API</a> with additional picklist values (e.g., purpose of transaction) and new data fields. These enhancements help ensure our partners and Corpay digitally capture all of the required information to meet global Compliance KYC requirements.</p>
<p><span style="color:rgb(56, 118, 29)"><strong class="slate-bold">Now Available</strong></span><span style="color:rgb(76, 17, 48)"><strong class="slate-bold"> </strong></span><strong class="slate-bold">- Released on: October 31, 2025.</strong> <strong class="slate-bold">Read </strong><a href="" target="_self">here</a><strong class="slate-bold">.</strong></p>
<p></p></AccordionItem>
</Accordion>

Upcoming Updates

<Callout attributes='{"isFitToPage":true,"dataType":"success","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Key identifiers and concepts used across Corpay Cross-Border APIs.</p>
</Callout>

*   **Client Code** - A unique 6-digit client identifier for each client account. Used in all endpoints as part of the URL.
    
*   **Partner ID** - Links multiple client accounts together. Used during the authentication procedure.
    
*   **Client Integration ID**\- Unique beneficiary ID that you can use in other endpoints.
    
*   **Tracker ID** - The unique tracker identifier assigned to a payment transaction.
    
*   **Payment** - Outgoing cashflow to a beneficiary.
    
*   **Settlement** - Incoming cashflow to Corpay.
    
*   **MCA** - Multi-Currency Accounts (Formerly known as FXBalance/CLIAB)

Common Terms

This section provides essential reference information to help you validate and configure your transactions accurately. You can access up-to-date details on supported currencies, countries, and regions, ensuring compliance with Corpay’s API requirements.

*   **Current API Version** - `1.8`
    
*   **Supported Currencies** - Use `GET /api/payCurrencies?product=Bene` to retrieve valid values.
    
*   **Supported Countries** - Use `GET /api/countries` to retrieve valid values.
    
*   **Supported States/Regions** - Use `GET /api/regions?Country=ISO2 country code` to retrieve valid values. See [GET Regions](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-help/regions)
    
*   **Download Postman Collection** - Click the top right menu.
    

<Callout attributes='{"isFitToPage":true,"dataType":"success","style":{"width":"100%","minWidth":"100%"}}'>
  <p>To request Sandbox credentials, please contact your account representative.</p>
</Callout>

Supporting Information

Each endpoint in the documentation shows the HTTP method and the relative path. To form the full URL, prepend the base path - [https://crossborder.corpay.com](https://https://crossborder.corpay.com)

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Depending on the stage of your implementation, the base path may be different. For <strong class="slate-bold">non-production environments (staging, QA, testing)</strong>, use the Beta base path: <a href="https://crossborder.beta.corpay.com" target="_self">https://crossborder.beta.corpay.com</a></p>
</Callout>
<Card attributes='{"isFitToPage":true,"style":{"width":"100%"}}'>
  <title>VALID REST URL</title>
  <description><ul class="slate-ul "><li class="slate-li "><div style="position:relative">{clientCode}</div></li><li class="slate-li "><div style="position:relative">GET /api/{clientCode}/0/benes/{beneID}</div></li><li class="slate-li "><div style="position:relative">GET https://crossborder.corpay.com/api/123456/0/benes/jsmith321</div></li></ul></description>
</Card>

Base URL

Most endpoints include examples of both successful and unsuccessful responses. In the Response window, click a status code to view the example.

Corpay Cross-Border follows standard HTTP status codes to indicate request success or failure.

Response Codes

Our RESTful API suite employs **OAuth2.0** standard authorization framework, which consists of a two-part flow that involves exchanging an HS256-signed JWT token for a `CMG-AccessToken`.

The partner-level and the client-level work in the following way:

*   Given `Issuer` - either the name of the Partner/Client ID (contained in the Claim Set) - and the Signature, you create an encoded JWT Token (hashed via HS256), which is inserted into the body of the request of this call (in the `assertion` field).
    
*   When creating the token, the `issued-at` and the `expiration` should be current and advisably set apart at an interval of 20 minutes, respectively. The `aud` value must always be set to `cambridgefx`.
    
*   Once the call is placed, the response provides an `access_code` which will be submitted to the `CMG-AccessToken` field in the header of the subsequent (Client-Level) requests. Since there is no call preceding the partner-level, there is no need to pass anything through `CMG-AccessToken` for the partner-level.
    

<Divider />

2-Token Auth

Sample payload for the JWT token generation:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"Plain text"}'>
  <CodeLine>  {</CodeLine>
  <CodeLine>  "iss": "test",</CodeLine>
  <CodeLine>  "iat": 1480103915,</CodeLine>
  <CodeLine>  "exp": 1480105116,</CodeLine>
  <CodeLine>  "aud": "cambridgefx",</CodeLine>
  <CodeLine>  "sub": ""</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

You can use this [sample JWT generator link](http://jwtbuilder.jamiekurtz.com/) to generate a token.

For the token, you must be current between the window of the issue and the expiry (`iat` and `exp`, respectively) of the Unix-Timestamp.

##### **IMPLEMENTATION NOTES:**

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">Algorithm has to be HS256.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">Assertion must be regenerated as it has an expiry time.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">Assertion value is an encoded JWT token that contains a security key provided by Corpay.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">iss&nbsp;(issuer) is the Corpay-provided partner ID.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">access_code expiry time is indicated by the parameter expires_in (in seconds) in the response body</span></div></li></ul>
</Callout>

Partner-level Token Login

The authentication on the Client-level is similar to the authentication process at the partner-level. There are two key differences in the JWT construction:

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p></p>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">access_code from the Partner Auth goes in the CMG-AccessToken Header of this API.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">API user ID is the iss (issuer) in the JWT token.</span></div></li></ul>
  <p></p>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">The access_code granted at the Client-level will be submitted to the CMG-AccessToken field in the Header of the subsequent calls in the current user session.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">access_code expiry time is indicated by the parameter expires_in (in seconds) in the response body.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">Expiry of the access_code can accommodate different use cases.</span></div></li></ul>
</Callout>

Client-level Token Login

The endpoints in this section are used to create functional beneficiary templates that comply with all country-specific regulatory requirements.

<Divider />

Beneficiary Workflow

The first call, `Beneficiary Rules`, outlines _what_ is required for the beneficiary template, `Create/Edit Bene` creates the template, and `View Bene` allows you to view the template.

Beneficiary Core

These endpoints assist with the creation and lookup of beneficiary information.

IBAN Validation is recommended for use in IBAN-enabled countries, while Bank Search is for countries that do not support IBAN.

Beneficiary Help

This set of endpoints deals with the _exchange_ of a currency pair and the _transfer_ of that exchanged currency to a beneficiary or a holding balance. The first three endpoints are the key elements of the Spot Workflow:

1.  Spot Rate
    
2.  Book Deal
    
3.  Instruct Deal
    

The other three endpoints are used to fetch rate and quote information:

1.  Lookup Orders
    
2.  Rate Resource
    
3.  Quotes

Spot Workflow

This is the first of two calls that are used to book a live rate as part of a Spot transaction. This call creates a temporary resource based on the live exchange rate (between a currency pair). To secure the rate, you must book the deal (`POST` [Book Deal](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/2-book-deal)).

The `lockside` determines which side of the pair will carry the base amount.

As market rates are constantly changing, this quote may expire before you book the deal. By default, the rate expires in 10 seconds.

The quote resource is in the response header under `Location`. This URL is the precursor to executing the `POST` [Book Deal](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/2-book-deal) endpoint.

<Image url="https://d24lr4zqs1tgqh.cloudfront.net/31555510-407c-4fa8-8879-bcdec66bb724.jpg" alt="" caption="" attributes='{"width":"617px","height":"139px"}'/>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Corpay maintains a list of all available currencies and ranks them from major to minor. This ranking is internal to Corpay and does not reflect any industry standard ordering. The internal ranking determines how the values for the <code class="slate-code">rateType</code> and <code class="slate-code">operation</code> parameters are expressed in the response.</p>
</Callout>

##### **IMPLEMENTATION NOTES:**

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Consider the rate to be available for 8 seconds, and 2 seconds for latency and other network effects. Refresh after that period of time, or there will be a time-out error.</p>
</Callout>

[1] Spot Rate

This is the second of two calls that are used to book a live rate as part of a Spot transaction. This call uses the `quoteId` returned by the `POST` [Spot Rate](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/1-spot-rate) call to book a deal using the quoted rate.

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>The quote obtained from <code class="slate-code">POST</code> <a href="https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/1-spot-rate" target="_self">Spot Rate</a> is valid for 10 seconds, after which it expires. If you don't book the deal before the rate expires, the response status will be <code class="slate-code">400 (Quote expired)</code>, and you will need to generate a new quote.</p>
</Callout>

<Divider />

##### **IMPLEMENTATION NOTES:**

<Card attributes='{"isFitToPage":false,"style":{"width":"60%"}}'>
  <title>IMPLEMENTATION NOTES:</title>
  <description><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Ensure you append the <code class="slate-code">/book</code> at the end of the resource.</div></li><li class="slate-li "><div style="position:relative">The terms deal number and order number have the same meaning.</div></li></ul></description>
</Card>

<Divider />

[2] Book Deal

Once the Spot Transaction has been booked, you can instruct the funds to a beneficiary or an internal holding balance (this is specified in the `payment` portion of this payload).

The settlement funds (the `settlement` portion) can come from a bank account or a holding balance. This call also specifies which settlement account to use for fees. In most cases, the account designated for fees contains the base currency (for example, if you are located in Canada, your fee settlement account will be a CAD account).

The total instructed amount does not have to equal the amount exchanged during the Spot Transaction, but it cannot exceed that amount.

This endpoint supports idempotency through the `requestId` parameter. If the request is repeated with the same `idempotencyKey` the endpoint will return the original booking result.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>If the deal is subject to the Regulation E remittance transfer rule as required by the Dodd-Frank Wall Street Reform and Consumer Protection Act (commonly referred to as Dodd-Frank), and the order includes at least one payment where the remitter classification is <code class="slate-code">Individual</code>, the response will include Reg E payment disclosure information. This is required by U.S. law for electronic funds transfers by individuals.</p>
</Callout>

[3] Instruct Deal

Allows you to view the following information for a specific order:

*   `regEDisclosure` - Reg E Disclosure information (if applicable)
    
*   `payments` - beneficiary details
    
*   `settlements` - settlement details
    
*   `orderDetails` - rates, amounts, trade details, etc.
    

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>If the order is subject to the Regulation E (Reg E) remittance transfer rule as required by the Dodd-Frank Wall Street Reform and Consumer Protection Act (commonly referred to as Dodd-Frank), and the order includes at least one payment where the remitter classification is 'Individual', the response will include Reg E payment disclosure information. This is required by U.S. law for electronic funds transfers by individuals.</p>
</Callout>

Lookup Orders

When you run the `POST` [Spot Rate](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/1-spot-rate) call, a resource is created that contains the conversion and quote information. This endpoint returns the resource details.

<Divider />

Rate Resource

This call lists all of the `GET Get Rate` requests after `POST Spot Rate` in chronological order. Even though the retrieved quotes may not have been booked, they still appear in this list.

To view the details of a particular quote, append the `quoteId` to the URL.

Quotes

This API returns an indicative rate and amount for a Spot transaction based on a live exchange rate (between a currency pair).

The `lockside` determines which side of the pair will carry the base amount. For example, for a EUR/USD spot deal, if lockside is set to the `payment` currency (which in this case is EUR), then the quoted amount will be the `settlement` currency (or USD in this case).

<Callout attributes='{"isFitToPage":true,"dataType":"error","style":{"width":"100%","minWidth":"100%"}}'>
  <p>This rate is indicative only and may change when you get a quote from <code class="slate-code">POST Spot Rate</code> for booking a deal.</p>
</Callout>

Indicative Rate

A Rate Order is an order to buy or sell currency at a specific rate or better. If the target rate becomes available before the order’s expiry date, the system will automatically book the deal. You can create Rate Orders for spot trades and for forward trades.

<Callout attributes='{"isFitToPage":true,"dataType":"error","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Important: A Rate Order is not guaranteed to fill.</p>
</Callout>

Rate Orders

Creates a new Rate Order. You can create Spot Rate Orders and Forward Rate Orders. Forward Rate Orders can be either Closed Forwards or Open Forwards.

Create Rate Order

Retrieves complete information for all of your Rate Orders.

<Divider />

See [View Rate Order Response](https://developer.crossborder.corpay.com/apidocscrossborder/rate-orders/view-rate-orders/view-rate-order-response) section for detailed explanations of the API response fields.

View Rate Orders

This endpoint permanently deletes the specified Rate Order. You cannot delete more than one Rate Order at the same time.

Delete Rate Order

Forward trades allow you to lock in to a specific exchange rate. You can then draw down against the forward to make payments at a future date.

Forwards and Drawdowns

Forward Contracts are an effective way to hedge against foreign exchange fluctuations by locking in the current FX rate and then settling that rate and amount at a future date. There are two types of forward agreements: Closed Forwards and Open Forwards.

*   A Closed Forward lets you lock in the current exchange rate, and receive foreign currency funds on a specified future date (also known as the maturity date). This type of contract requires you to complete the transaction on the date it expires (the Maturity Date) at the agreed rate of exchange. A Closed Forward is settled in its entirety on the maturity date.
    
*   With an Open Forward, you also lock in the current exchange rate for a future date value and settlement, but unlike a Closed Forward, you can draw down the funds at any time within the specified period. You do not need to wait until the maturity date. All the drawdowns are processed at the agreed-upon rate. The trade can be settled either in full or in part as long as the full amount has been paid by the maturity date.
    

The following identifiers are created for each completed forward:

*   The `ordNum` is the alpha-numeric transaction identifier. It is the same as the deal number except that it is prefixed with 'OFD' (i.e. OFD40123456).
    
*   The `forwardId`/`paymentInstructionId` is the numeric forward identifier (i.e. 1386511).
    
*   The `quoteId` is the identifier of the forward quote rate resource (i.e. cc2999ba7eb84e19a158a8bf0f21296e).
    

These three endpoints are the key elements of the Forwards workflow.

1.  Request Forward Quote
    
2.  Book Forward Quote
    
3.  Complete Order
    

The other two endpoints are optional to get more information:

*   Retrieve Forward Quote
    
*   Forward Instructions

Forwards

The drawdown workflow withdraws or instructs a specified amount from the available balance of the forward contract. This can happen on the 'Maturity' date, or, in the case of an Open forward, this can happen on or after the open date.

Drawdowns

The cancellation workflow creates a ‘mirror-reverse’ transaction for the deal you are cancelling. For example, the cancellation of a USD/CAD spot deal is a CAD/USD transaction. When you provide the order number of the original Spot, the rest of the information is auto-retrieved (such as amounts and currencies).

Orders created via Spot and Forward workflows can be cancelled.

Just as the `POST` [Spot Rate](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/2-book-deal) and `POST` [Book Deal](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/post-2-book-deal) workflow has a timer, `Request Cancellation` and `Book Cancellation` also has an allotted window of time (the default is 10 seconds).

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Note:</strong> There is no timer between when you book a deal and when you can cancel it; however, we recommend that you request the cancellation within a reasonable time, taking into account currency fluctuations.</p>
</Callout>

Cancel Order

To use this call, you need to have an `orderNumber`, that is, you need to have booked a quote. The endpoint uses the order number in the URL to identify the currencies and amounts of the order you want to cancel. Unlike `POST` [Spot Rate](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/1-spot-rate), there is no quote resource created by calling this endpoint. This is because the rate of the initial transaction is used.

The response contains the link to the `POST` [Book Cancellation](https://developer.crossborder.corpay.com/apidocscrossborder/cancel-order/book-cancellation).

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>If the client is subject to the Regulation E (Reg E) remittance transfer rule as required by the Dodd-Frank Wall Street Reform and Consumer Protection Act (commonly referred to as Dodd-Frank), the entire order can be cancelled without any charges if the following conditions are met:</p>
  <ul class="slate-ul "><li class="slate-li "><div class="slate-div"><span style="color:#252c3e">There is at least one payment instruction in the deal with a remitter whose classification is 'Individual'.</span></div></li><li class="slate-li "><div class="slate-div"><span style="color:#252c3e">The payment is cancelled within 30 minutes of it being booked or instructed.</span></div></li></ul>
</Callout>

Request Cancellation

The link for Book Cancellation is provided in the response body of the `POST` [Request Cancellation](https://developer.crossborder.corpay.com/apidocscrossborder/cancel-order/request-cancellation). If this endpoint is successful, an order number is granted.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Subscribe to the<a href="https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events/payment" target="_self"> Payment Events</a> webhooks to receive real-time notifications when a payment is cancelled.</p>
</Callout>

Book Cancellation

Similar to how the beneficiary template creates a record for the beneficiary and bank account to be paid, the settlement account template is for the bank account that is issuing the payment. The Settlement Account template is also known as the ‘Incoming Funds Template’. Once complete, these accounts can be used to settle transactions and payments. Accounts created through this workflow are non-Corpay bank accounts. Multi-Currency Accounts (previously called FXBalance) or Corpay holding account templates are not created in this same way.

Settlement Accounts

This endpoint enables you to view all settlement accounts for this client.

View Template

This call returns a list of the Corpay Multi-Currency Accounts (previously called FXBalance) for this client. Multi-Currency Accounts are internal holding balances for currency-specific deposits. They are an alternative settlement option.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Multi-Currency Accounts cannot be created through the API. They are set up using a back-office process.</p>
</Callout>

View Multi-Currency Accounts

This call returns the transaction history of the specified Corpay Multi-Currency Account (previously called FXBalance).

<Divider />

#### RESPONSE BODY

<Divider />

Multi-Currency Accounts History

This call returns details about incoming funds received by a Multi-Currency Account, including funds directed to any downstream client Multi-Currency Accounts.

Incoming Funds Details

The endpoints in this section are used to manage Multi-Currency Account nickname.

Manage Multi-Currency Accounts Nickname

Remitters are used when a payment is initiated by a third party. This endpoint allows you to create the remitters that can then be attached to payments.

Remitter

Similar to the `POST` [Create/Edit Bene](https://developer.crossborder.corpay.com/apidocscrossborder/beneficiary-workflow/beneficiary-core/create-edit-bene) call, the `PUT` method is used for better error handling due to the idempotency of `PUT` requests. The URL query string contains the Remitter ID, which must be unique. You can either use [GUID](https://guidgenerator.com/), as it has a very low chance of collision, your own hash, or some deterministic prefix in order to make sure it is unique.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>The only characters allowed in the <code class="slate-code">uniqueRemitterId</code> are alphanumeric (a-zA-Z0-9), dash (-), and underscore (_).</p>
</Callout>
<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Remitter identifiers longer than 34 characters are now automatically truncated when processing the SWIFT MX message.</p>
</Callout>

Remitter Add/Edit

This call retrieves the details of a remitter.

**Note:** The URL is the same as `PUT` [Remitter Add/Edit](https://developer.crossborder.corpay.com/apidocscrossborder/remitter/remitter-add-edit), which creates or modifies a remitter, but this is a `GET` call rather than a `PUT`.

Remitter Retrieve

The Mass Payment workflow is a two-step payment-aggregation workflow designed to make payments to multiple beneficiaries at the same time, using a single call.

The only limitation is the currency-specific account limit of any currency being used for settlement (as outlined in the onboarding agreement).

Mass Payments

This is the first of two calls that are used to book multiple payments. You send the payment information in the request, and the response returns the rate information.

To secure the rate(s), you must execute the next call, `POST` [Book Multiple Payments](https://developer.crossborder.corpay.com/apidocscrossborder/mass-payments/book-multiple-payments), before the rate expires (usually 10 seconds).

<Divider />

Multiple Payments

This is the second of the two calls that are used to book multiple payments. The URL that you need to send can be found in the response to the preceding call - `POST Multiple Payments` under `BOOK_PAYMENT`.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">The quote obtained from POST Multiple Payments is valid for 10 seconds, after which it expires. If you don't book the deal before the rate expires, the response status will be 400 (Quote expired). If that happens, you will need to generate a new quote.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">The quoteKey and loginSessionId params are contained in the URL, which is a unique feature of this workflow.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">This endpoint supports idempotency through the loginsessionId parameter. If the request is repeated with the same idempotencyKey the endpoint will not process the new data and book again (loginsessionId is returned in the response in the previous call under BOOK_PAYMENT).</span></div></li></ul>
</Callout>

Book Multiple Payments

Clients/Partners can now trace the details and status of SWIFT payments after the payment has exited the Corpay bank account and is en route to the beneficiary's bank account.

Currently, this feature is only available for payments travelling via the SWIFT Network - _Wires_ - (i.e. method is Wire). **EFT/iACH payments are not currently supported**.

Payment Tracking

The confirmation endpoint displays a channel-specific payment confirmation message. To receive a successful response, the payment must be _**successfully instructed.**_ (status: `200` on `POST` [Instruct Deal](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/post-3-instruct-deal)).

Rather than `ordNum`, this endpoint uses the `paymentInstructionId` in the URL. You can get the `paymentInstructionId` by using `GET` [Lookup Orders](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/get-lookup-orders)

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <ul class="slate-ul "><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">Messages are provided in full only if the payment has exited the Corpay bank account and is en route to the beneficiary's bank account. Therefore, if the number of returned messages is 0, even though the payment has been booked, it just means the funds haven't left the Corpay bank account.</span></div></li><li class="slate-li "><div style="position:relative"><span style="color:#252c3e">The endpoint will return one or more MT103 or pacs 008 messages in the response field when the&nbsp;Method&nbsp;is set to&nbsp;W&nbsp;(Wire) and an MT103/pacs 008 is found for the specified&nbsp;paymentInstructionId. If the&nbsp;Method&nbsp;is set to&nbsp;C&nbsp;(MCA Balance) or&nbsp;E&nbsp;(EFT), the response field will be blank. No other MTxxx messages will be returned.</span></div></li></ul>
</Callout>

##### SWIFT MESSAGE FIELDS

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"718472a7-753d-4763-8cf4-bb17496a149b","title":"Title"},{"id":"86697745-6966-415e-9140-b099e784a9ea","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Field</strong></p></table-cell>
    <table-cell><p class="slate-p "><strong class="slate-bold">Name</strong></p></table-cell>
    <table-cell><p class="slate-p "><strong class="slate-bold">Description</strong></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:20</p></table-cell>
    <table-cell><p class="slate-p ">Transaction reference number</p></table-cell>
    <table-cell><p class="slate-p ">Message number assigned by the sender.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:23B</p></table-cell>
    <table-cell><p class="slate-p ">Bank operation code</p></table-cell>
    <table-cell><p class="slate-p ">Type of operation.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:32A</p></table-cell>
    <table-cell><p class="slate-p ">Value date, Currency, Interbank settled amount</p></table-cell>
    <table-cell><p class="slate-p ">Date format is <em class="slate-italic">YYMMDD</em>. Currency is three-letter ISO code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:33B</p></table-cell>
    <table-cell><p class="slate-p ">Currency, Original ordered amount</p></table-cell>
    <table-cell><p class="slate-p ">Three-letter ISO currency code and amount of instruction.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:50A, F, or K</p></table-cell>
    <table-cell><p class="slate-p ">Ordering customer (payer) or address of the remitter</p></table-cell>
    <table-cell><p class="slate-p ">Customer ordering the transaction.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:52A or D</p></table-cell>
    <table-cell><p class="slate-p ">Ordering institution</p></table-cell>
    <table-cell><p class="slate-p ">Payer's bank.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:53A, B, or D</p></table-cell>
    <table-cell><p class="slate-p ">Sender's correspondent (bank)</p></table-cell>
    <table-cell><p class="slate-p ">Account or branch of sender.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:54A, B, or D</p></table-cell>
    <table-cell><p class="slate-p ">Receiver's correspondent</p></table-cell>
    <table-cell><p class="slate-p ">Branch or FI where funds are available to receiver.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:56A, C, or D</p></table-cell>
    <table-cell><p class="slate-p ">Intermediary bank</p></table-cell>
    <table-cell><p class="slate-p ">FI through which transaction must pass.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:59 or 59A</p></table-cell>
    <table-cell><p class="slate-p ">Beneficiary customer</p></table-cell>
    <table-cell><p class="slate-p ">Recipient of the funds.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:57A, B, C, or D</p></table-cell>
    <table-cell><p class="slate-p ">Account with institution</p></table-cell>
    <table-cell><p class="slate-p ">Beneficiary's account.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:70</p></table-cell>
    <table-cell><p class="slate-p ">Remittance information</p></table-cell>
    <table-cell><p class="slate-p ">Information about the transaction.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:71A</p></table-cell>
    <table-cell><p class="slate-p ">Details of charges.</p></table-cell>
    <table-cell><p class="slate-p ">Specifies which party is responsible for fees - OUR, SHA, or BEN.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:72</p></table-cell>
    <table-cell><p class="slate-p ">Sender to receiver information</p></table-cell>
    <table-cell><p class="slate-p ">Additional information for the receiver.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">:77B</p></table-cell>
    <table-cell><p class="slate-p ">Regulatory reporting</p></table-cell>
    <table-cell><p class="slate-p ">Regulatory information required by the sender or receiver country.</p></table-cell>
  </table-row>
</Table>

Payment Channel Information

This endpoint retrieves the tracker identifier of a specific payment by passing its `paymentInstructionId`. You can get the `paymentInstructionId` by using `POST` [Instruct Deal](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/post-3-instruct-deal) or `GET` [Lookup Orders](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/get-lookup-orders).

Payment Tracking Lookup

Trace the detailed information of a payment transaction by passing its `trackerId` . You can get the trackerId by using `POST` [Instruct Deal](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/post-3-instruct-deal) or `GET` [Lookup Orders](https://developer.crossborder.corpay.com/apidocscrossborder/spot-workflow/get-lookup-orders) or `GET` [Payment Tracking Lookup](https://developer.crossborder.corpay.com/apidocscrossborder/payment-tracking/get-payment-tracking-lookup).

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <ul class="slate-ul "><li class="slate-li "><div class="slate-div"><div class="slate-div"><p class="slate-p ">/api/{clientCode}/0/payment-tracking/{trackerId}</p></div></div></li><li class="slate-li "><div class="slate-div"><div class="slate-div">Payment Events</div></div></li></ul>
</Callout>
<Callout attributes='{"isFitToPage":true,"dataType":"error","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Payment Tracking does not currently support exotic currencies. Please contact your account representative for more information.</p>
</Callout>

**CHARGE AMOUNT AT EACH CORRESPONDENT BANK IS CALCULATED AS:**

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>A. First Event</CodeLine>
  <CodeLine>  charge_amount = instructed_amount - interbank_settlement_amount</CodeLine>
  <CodeLine>  B. Corresponding Events</CodeLine>
  <CodeLine>  charge_amount = interbank_settlement_amount/confirmed_amount (previous event) - interbank_settlement_amount/confirmed_amount (current event) </CodeLine>
</CodeBlock>
<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">NOTE</strong>: <code class="slate-code">interbank_settlement_amount</code> and <code class="slate-code">confirmed_amount</code> are the amounts forwarded to the next correspondent bank or credited to the beneficiary.</p>
</Callout>

**See the** [Payment Tracking Response](https://developer.crossborder.corpay.com/apidocscrossborder/payment-tracking/payment-tracking-1/get-payment-tracking-response) **section for detailed explanations of the API response fields.**

The client onboarding API allows our integrated partners to expedite the onboarding process of their downstream clients. Partners submit the client onboarding data, upload the required verification documents, and generate the auth key. Once the authentication key is generated, the client gains access to Corpay's API. Get [Started](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client).

Client Onboarding

Partner Onboarding Workflow

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title="Submit Client Onboarding Data"><p>Onboard a client via the <a href="https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client/client-onboarding-1" target="_self">client onboarding</a> request. Upon successful submission of data, a unique <code class="slate-code">clientOnboardingId</code> is generated.</p></Step><Step stepNumber="2" title="Upload Verification Documents"><p>Submit the required verification documents for the approved onboarded client through the <a href="https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client/submit-onboarding-files" target="_self">document submission request.</a> This is a mandatory requirement to complete the client onboarding process.</p></Step><Step stepNumber="3" title="Generate Authentication Key"><p>Once the onboarding request is approved, generate auth keys via the <a href="https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client/authsecret-keys" target="_self">AuthSecret Keys</a> request. This key enables your downstream client to securely access Corpay’s API suite based on assigned permissions.</p></Step><Step stepNumber="4" title="Track Status"><p>Optionally, subscribe to the <a href="https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events/client-onboarding-2" target="_self">Client Onboarding Webhook</a> to receive real-time notifications when the onboarding request is approved and the secret key is generated.</p></Step></Steps><Callout attributes='{"isFitToPage":false,"dataType":"error","style":{"width":"60%","minWidth":"60%"}}'>
  <p>You cannot onboard duplicate client profiles.</p>
</Callout>

Onboard Client

This folder defines picklist values used across the [Client Onboarding API](https://developer.crossborder.corpay.com/apidocscrossborder/client-onboarding/onboard-client/client-onboarding-1). These values help ensure consistency and accuracy when creating or updating onboarding requests.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>The picklist endpoints are updated periodically to reflect changes in Corpay's business rules and regulatory requirements. We may add new values or modify existing ones as required<span style="background-color:rgb(250, 250, 250);color:rgb(66, 66, 66)">. </span>Please refer to our <a href="https://developer.crossborder.corpay.com/apidocscrossborder/what-s-new" target="_self">API release notes</a> to stay informed of changes.</p>
</Callout>

Reference Data

Webhooks let you subscribe to events and receive real-time notifications when those specific events occur. (For example, payment processed, funds received into your account, or a client onboarded). Instead of polling the API for updates, webhooks push data to your endpoint as soon as the event happens, improving efficiency and reducing unnecessary API calls.

### Advantages of using webhooks:

*   Receive real-time updates
    
*   Reduce API traffic and server load
    
*   Sync the data as it changes
    
*   Ensure timely and reliable updates

Webhooks

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title="Create your webhook endpoint"><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Set up a publicly accessible HTTPS URL on your server.</div></li><li class="slate-li "><div style="position:relative">Ensure it returns a 2xx HTTP status code to acknowledge receipt.</div></li></ul></Step><Step stepNumber="2" title="Register with Corpay"><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Contact your account representative and provide your webhook URL.</div></li></ul></Step><Step stepNumber="3" title="Subscribe to events"><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Specify the events you want to subscribe to. For the full list of events, refer to the <a href="https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events" target="">supported events</a> section or contact your account representative.</div></li></ul></Step><Step stepNumber="4" title="Test and Deploy"><ul class="slate-ul "><li class="slate-li "><div style="position:relative">For BETA testing, HTTP URLs are allowed</div></li><li class="slate-li "><div style="position:relative">For Production, HTTPS is mandatory.</div></li></ul></Step><Step stepNumber="5" title="Enable on Production"><ul class="slate-ul "><li class="slate-li "><div style="position:relative">Once verified, enable your public HTTPS URL webhook endpoint in production.</div></li><li class="slate-li "><div style="position:relative">Register your URL with Corpay. Any updates to the registered URL must be informed to your account representative to continue receiving notifications.</div></li></ul></Step></Steps><Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Always test your webhook in the Beta environment before enabling it in production to ensure it correctly handles notifications.</p>
</Callout>

Subscribe to Webhooks

<Divider />

### Acknowledgement Receipt

*   Your server must respond with a `2xx` HTTP status code.
    
*   If Corpay does not get a `2xx` response, it will be logged as an error, and the system will attempt a retry, according to the retry logic described below.
    

<Divider />

### Retry Logic

Webhooks can fail if your endpoint is unavailable, returns an error response, or takes too long to respond. If webhook notifications repeatedly fail:

*   Corpay will **retry for up to 24 hours** using exponential backoff (instead of retrying immediately, the system waits longer between retries).
    
*   **If all retries fail within 24 hours, the webhook is automatically disabled**. To reactivate the notifications, please contact your account representative.

Receive Webhooks Notifications

If you’re not receiving notifications, check for:

*   Endpoint not publicly accessible
    
*   Non-2xx HTTP responses
    
*   Slow response times causing timeouts
    
*   Incorrect event subscriptions
    
*   Signature validation failure
    
*   Notifications may be manually disabled by your account representative
    

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Contact your account representative to manage subscriptions or reactivate disabled webhooks.</p>
</Callout>

Troubleshoot Notifications

Corpay sends webhook notifications for the following events:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"50ea8465-5aaa-4d41-997f-9f98141fb47e","title":"Title"},{"id":"1e442b10-ab88-4a9e-815a-1b76251f48f7","title":"Description"},{"id":"9615e4d4-e345-41b7-80a1-ea41256c03fa","title":"Title"},{"id":"3ae93abb-2456-45b0-949d-40d24e6c716c","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Request</strong></p></table-cell>
    <table-cell><p class="slate-p "><strong class="slate-bold">Event</strong></p></table-cell>
    <table-cell><p class="slate-p "><strong class="slate-bold">Status</strong></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><a href="https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events/payment" target="_self">Payment GPS</a></p></table-cell>
    <table-cell><p class="slate-p ">PaymentAccepted, PaymentProcessed, PaymentTrackingInfoReceived, PaymentCancelled, PaymentReturned, PaymentCancelledByClient, PaymentProcessedNonSwift</p></table-cell>
    <table-cell><p class="slate-p ">Active</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><a href="https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events/client-onboarding" target="_self">Client Onboarding</a></p></table-cell>
    <table-cell><p class="slate-p ">AccountApproved - Onboarding request approved and secret keys generated.</p></table-cell>
    <table-cell><p class="slate-p ">Active</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><a href="https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events/incoming-funds" target="_self">Incoming Funds Credited to Multi-Currency Account</a></p></table-cell>
    <table-cell><p class="slate-p ">IncomingFundsCredited</p></table-cell>
    <table-cell><p class="slate-p ">Active</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><a href="https://developer.crossborder.corpay.com/apidocscrossborder/webhooks/supported-events/exceptions" target="_self">Exceptions</a></p></table-cell>
    <table-cell><p class="slate-p ">PaymentOnHold</p></table-cell>
    <table-cell><p class="slate-p ">Active</p></table-cell>
  </table-row>
</Table>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>You can currently subscribe to events with an <strong class="slate-bold">active</strong> status.</p>
</Callout>

Sections

Spot Workflow

On this page