Corpay Cross-Border Solutions | API Resources

Corpay will enforce validation rules on the POST Create/Edit Beneficiary endpoint, allowing only valid region and ZIP/postal code values. If invalid data is provided in these fields, the endpoint will return a 400 Bad Request with an appropriate error message.
We are reaching out to you directly as we have observed that some of the region/zip code values provided in your recent beneficiary payment instructions are invalid.
Therefore, to comply with the updated regulatory requirements, we kindly request that you update your API integration to ensure only valid region and postal code values are provided for U.S. and Canadian beneficiaries by the end of Q1.
We will of course be available to assist with the necessary integration changes in which we have outlined the next steps below (this includes scheduling a call to go through the required changes in detail).

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.

Specifically for API integrated partners, when using the POST Create/Edit Bene endpoint, if a valid region name or code is not specified the request will return a 400 Bad Request error.

Valid region values can be retrieved using the GET Regions endpoint, where both the ID and Code response values are accepted when creating beneficiary templates. Regarding valid postal codes, the accepted format for US and CA will be returned in our GET Beneficiary Rules endpoint.

IMPORTANT NOTE: This validation enforcement was deployed into Production environment on 7th April 2025. Corpay will continue to collaborate with our existing partners who are temporarily exempt from this new validation rule whilst they made the necessary development changes.

The defaultInternalComment field, previously used in the Create/Edit Bene API endpoint to enter “For Further Credit (FFC)” details, is now renamed to furtherCreditDetails to provide a more intuitive and descriptive label. This update will also be reflected in the Beneficiary Validation and the Get Beneficiary Rules endpoint.

Note: As of 25th April 2025, the old field name is no longer supported. If the old field name is used, the API will return a 200 Success response but the FFC information will not be saved for that bene. To ensure FFC details are saved correctly, partners must use the new field name furtherCreditDetails in the API request.

SWIFT will decommission the current version of its payment tracking service, SWIFT GPI v4, by the end of November 2024. Users of this service will need to transition to SWIFT GPI v5.

What does this change mean for our partners using Corpay’s Payment GPS API?

We are pleased to confirm that no changes are required for partners using Corpay Cross-Border’s Payment Tracking endpoints to retrieve SWIFT GPI v5 tracking statuses. Corpay has already completed the necessary updates to implement and deploy SWIFT GPI v5 capabilities within our Payments GPS product offering.

Over the past few weeks, we have thoroughly tested the SWIFT GPI v5 changes to ensure our Payments GPS API continues to provide accurate tracking statuses on the payment network. However, if you encounter any issues, discrepancies, or have questions about this update, please don’t hesitate to reach out to us.

Finally, we would like to extend our sincere thanks to our pilot partners who helped test the SWIFT GPI v5 changes ahead of the wider Production deployment. Your support and invaluable feedback played a crucial role in the success of the testing phase, and we truly appreciate your contributions.

After reviewing the results of our recent partner product feedback and ideas submission, many of you requested a dedicated beneficiary validation API endpoint. This would allow you to test beneficiary details without creating a template on Corpay’s side if the details pass all validation checks. Previously, partners could only use Corpay’s ‘POST Create/Edit Bene’ endpoint to validate beneficiary data.

We are therefore pleased to confirm that we have now developed and deployed a new POST Beneficiary Validation endpoint. This will enable partners to validate a new beneficiary template submission without creating the template if the validation is successful.

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 our POST Create/Edit Beneficiary endpoint, entering a PO Box address in the beneficiary address fields will now return a REGEX_MISMATCH error. This restriction currently applies to Australia, Canada, and Mexico which is now also reflected in the returned address RegEx of our GET Beneficiary Rules endpoint. The update ensures that a complete physical address is provided, as required by regulatory standards

A few partners noticed a discrepancy in the header documented for our POST Partner-level Token Login endpoint. Specifically, there was a header entry titled CMG-AccessToken with a value of “toBeDiscontinued.” If you have downloaded our API collection into your Postman instance or codebase, this header may also appear in your Production environment.

Corpay’s development team has confirmed that this header should not be included in the POST Partner-level Token Login endpoint. We have since removed it from our documentation. If you are currently passing the CMG-AccessToken with the ‘toBeDiscontinued’ value in this endpoint’s header, please ensure it is removed. This has been identified as a potential root cause of some recent timeout errors partners have encountered when authenticating with our API.

CMG-AccessToken ‘toBeDiscontinued’ header has now been removed from our API documentation.

Previously, when using Corpay’s Mass Payment APIs, the payment GPS tracker Id’s were not returned in the POST Multiple Payment response. Therefore, clients would need to make a subsequent call to our GET Lookup Orders API to retrieve the payment tracker Id’s in which they weren’t always available straight away.

We have now deployed an update in which the payment GPS tracker Id’s are now returned immediately in the POST Multiple Payment API response. This removes the need to make any subsequent follow-up API requests and allows clients to store the tracker Id’s during the Mass Payment workflow immediately.

You can find an example of the update below:

As part of our continuous development of Corpay’s Onboarding API suite, we have now added an Authentication Retrieval API endpoint. Previously, when a partner onboarded a new client account via the API, the secret keys for authentication were sent via an encrypted email. However, our new GET AuthSecret Keys endpoint will now allow partners to retrieve the secret keys for a newly onboarded client account directly via the API (helping to automate the end-to-end flow).

This new endpoint helps to further streamline the client onboarding process for all our integrated partners. Retrieving the secret keys via the API significantly reduces the turnaround time of a client’s account being operational and ready for use with our wider services.

*Future Update: In Corpay’s first iteration of its upcoming Webhook deployment (scheduled for Q3), a push notification subscription will be available for the Onboarding API. This will allow for a push notification to be sent to our partners whenever one of their onboarded client accounts has been approved by Corpay’s Compliance team.

You can find an example of the GET AuthSecret Keys below:

What Is ISO 20022?

ISO 20022 is an international standard for electronic data interchange between financial institutions – a universal language that allows different payment systems around the world to communicate more effectively.
Unlike older messaging standards, ISO 20022 uses a flexible, XML-based format, enabling the inclusion of richer and more structured data in payment messages. This means more detailed information can accompany each transaction, facilitating better processing and compliance.

Corpay is now in the process of transitioning to ISO 20022. Key milestones include:

SWIFT’s Migration: SWIFT began its migration to ISO 20022 for Cross-Border payments in March 2023, with a coexistence period in place until November 2025.
Domestic Implementations: Various countries are adopting ISO 20022 for their domestic payment systems, each with specific timelines and requirements.

Why Is ISO 20022 Important?

The adoption of ISO 20022 brings several significant benefits:

Enhanced Data Quality: The structured format allows for more precise information to travel with the payment, reducing errors and ambiguities in processing.
Improved Compliance: More detailed data can result in better monitoring and compliance with regulations, aiding in the fight against financial crimes.
Operational Efficiency: Standardization across systems leads to streamlined processes and reduced operational costs.
Global Interoperability: A common messaging standard facilitates smoother Cross-Border transactions, benefiting the wider international trade and finance community.
Innovation Enablement: Rich data opens doors for the development of more advanced analytics, AI applications, and improved customer experience.

As part of our continued commitment to payment modernization and global compliance, Corpay is also introducing enhancements aligned with ISO 20022 standards. These updates affect both our UI platform and API endpoints, providing richer data structures and a more standardized experience.

What’s Changing?

You’ll begin to see a blend of MT (SWIFT legacy) and MX (ISO 20022 XML-based) messages across your payment workflows. Our goal is to ensure you have the right information at your fingertips as you transition with us.
To support you, we’ve outlined a few key differences to help you navigate the format changes:
 
Terminology
MT – Current legacy messaging format. Below table is focused on MT103
MX – New ISO 20022 messaging format. MT103 is referred to pacs.008

What to Look For

Across all platforms—Corpay Cross-Border Web, Corpay Online, and Corpay APIs—you may see either message type (MT or MX) during the transition. This depends on the format Corpay uses to process each payment.

We’re here to help you adapt to these enhancements smoothly. Our updated API documentation will reflect these changes shortly and include example responses for MT and MX formats.

High-level, endpoints such as the GET Payment Tracking endpoint for Payments GPS, are already MX-ready, and your responses may soon begin returning structured ISO 20022 data. Additionally, the GET Payment Channel Information endpoint will now return either the SWIFT MT103 or ISO equivalent MX messaging.

Please connect with your dedicated account representative or reach out to us directly at CrossBorderSupport@Corpay.com if you have any questions, or for further assistance.

Following the recent enforcement of valid region and postal code values when creating beneficiaries, additional regulatory and banking requirements are coming into effect for payment initiation and execution.

One of these new requirements is the mandatory inclusion of a valid Purpose of Payment (POP) when instructing payments. Specifically, when submitting a payment via the following endpoints you will need to provide a Corpay-accepted POP value in the purposeOfPayment request field:

POST Instruct Deal
POST Multiple Payments
POST Book Drawdown

You can retrieve the list of accepted POP values using the GET Purpose of Payment endpoint. Each returned object includes an id which must be used in your payment requests. If the purposeOfPayment field is left blank or populated with an invalid value, a 400 Bad Request error will be returned.

Enforcement Timeline

This validation is already enforced for all new clients and partners recently onboarded with Corpay. For existing partners, enforcement will begin in approx. 90 days, with deployment planned for the week commencing August 25th, 2025.

Next Steps

We have identified which existing partners are currently submitting invalid POP values and will be reaching out directly to support you with this update.

Important Note

While the POP list is consistent for most currencies, certain currencies—such as local INR and wire CNH payments—have unique POP value lists. Using INR as an example, there is a different POP list for INR wires vs. INR EFT. Therefore, it is essential to use the correct POP ID for the corresponding currency and payment method.

We are also planning to expand the POP list in the near future and will notify you once that update is available.

If you have any questions on this topic, please don’t hesitate to contact your Corpay account representative.

Currently, our POST Create/Edit Bene API allows users to edit the currency field of existing beneficiary templates. However, this has been identified as a risk, as the API does not trigger revalidation or request updated banking details when the currency is changed—leading to potential issues with future outbound payments.

To align with best practices and ensure consistency with the Corpay Cross-Border web platform (where the currency field is already locked for edits), we will restrict editing of the currency field on existing beneficiary templates via the API.

Once enforced, any attempt to edit the currency of an existing beneficiary template via the API will result in a 400 Bad Request response indicating that this is a non-editable field.

Enforcement Timeline

This change will be enforced in approx. 90 days, with deployment planned for the week commencing August 25th, 2025.

Next Steps

We have identified partners who are currently editing the currency field on existing templates and will reach out directly to offer support during this transition.

Recommended Action: Going forward, if a beneficiary's currency needs to be changed, you should create a new beneficiary template via the API rather than editing the existing one.

If you have any questions on this topic, please don’t hesitate to contact your Corpay account representative.

One of the key pieces of feedback we received from our partners in last year’s survey was the desire to expand our webhook (push notification) capabilities.

We’re therefore pleased to share that, as part of our Q2 development roadmap, we are introducing two new webhook subscription types:

Incoming Fund Notifications: Receive a push notification when incoming funds are applied to your Multi-Currency Account (MCA) or a pending payment.
Payments on Hold: Receive a push notification if one of your payments is placed on hold by our Compliance or Problem Investigation teams.

We are targeting deployment of these new webhook capabilities by the end of Q2, and we’ll continue to keep you informed as we progress.

Interested in early access?

If you’d like to be one of our pilot clients and gain early access to these webhook features, please reach out to your Corpay Account Manager.

Another key focus area for us over the upcoming months is to release further enhancements on our Onboarding API. This involves expanding our picklist values for certain fields (such as purpose of transaction) as well as adding new data fields that partners can populated.

These enhancements are aimed at ensuring our partners and Corpay can continue to digitally capture all of the required information needed to satisfy Compliance KYC requirements globally.

We will update you as timelines become known for these Onboarding API updates. Thank you to all our partners who have been early adopters of our Onboarding API, your feedback and patience has been valuable!

What is the Event?

Corpay’s Forwards creation workflow has been updated in the v1.8 API suite.

Who is Impacted?

Users of Corpay Cross-Border’s Forwards API functionality.

What are the details?

Corpay’s POST Accept Terms API endpoint was deprecated on 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 was 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 API endpoint.

Scheduled Event Time?

Removed on August 26th, 2023.

Contact:

If you have any questions regarding this Production API update, please contact: technicalsales@corpay.com

As detailed in the ‘Beneficiary Validation Best Practices’ section, Corpay will be enforcing SWIFT BIC as a mandatory field when creating beneficiaries — originally set for December 4th. This means that when creating beneficiary templates of any currency/country via the POST Create/Edit API endpoint, you will be required to populate the swiftBicCode parameter. This change will also be reflected in our GET Beneficiary Rules API endpoint in which the swiftBicCode parameter will always show as ‘IsRequired – True’ (meaning it is a required field).

Furthermore, we will soon be updating our Beta (sandbox) environment to enforce SWIFT BIC. This will allow our partners to test how this change may impact their current beneficiary workflow integrations with Corpay’s API ahead of the Production deployment date. We will send an additional communication once the Beta environment has been updated with the new SWIFT BIC requirement in which the regEx for SWIFT will be: ^[A-Z0-9]{8,11}$.

We are postponing the effective date to develop a beta environment and additional support mechanisms to lessen the impact of the transition on our partners and clients. We are committed to moving to mandatory SWIFT BIC fields in the near future.

An IBAN (International Bank Account Number) is used to identify an individual account (the ultimate beneficiary) within banking institutions.

Corpay strongly recommends including IBAN for any currency directed to an IBAN country.

The Corpay team greatly values our partnership! Please reach out to your Corpay Representative for any questions related to our Currency Capabilities, Product and Technology offerings.

*Please note: Where SWIFT/BIC and IBAN are not currently mandatory, this is subject to change with a 90 day notice period.

Beneficiary Rules (Template Guide)

The GET Beneficiary Rules endpoint allows partners to retrieve the required data fields for creating beneficiary templates and initiating payments. Requirements are based on:

Country
Currency
Beneficiary Type (Business or Individual)
Payment Method (Wire or Local)

The API will then return the key requirements/rules needed to successfully create the beneficiary template including:

Mandatory fields required for the POST Create/Edit Bene call.
Regex validation patterns, defining field format, structure, and character length.
Country-specific regulatory requirements, such as contact information and tax codes.

Benefits:

Partners can dynamically display the correct input fields and formats within their own UIs.
Reduces the chance of input errors and improves the success rate of beneficiary creation and payment execution.

IBAN Validation

A commonly used tool our partners incorporate into their beneficiary management flows whenever the account number is an International Bank Account Number (IBAN) is our POST IBAN Validation endpoint. This allows them to validate in real-time whether the IBAN provided by a customer is valid (i.e., it meets the formatting and character length requirements for that country).

In summary, it allows partners to:

Validate that the IBAN meets country-specific format and length requirements
Retrieve associated bank details, including:
- SWIFT BIC
- Routing Code
- Bank Name
- Bank Address

Benefits:

Ensures the IBAN is valid and correctly formatted.
Enables auto-population of bank fields, reducing manual input and minimizing errors.

Bank Search

For non-IBAN countries, partners can utilise our GET Bank Search API to retrieve results based on specified query criteria. Again, this allows partners to retrieve the corresponding banking information associated with the details provided and allows the partner/user to auto-populate the required banking information with valid data.

Search criteria that can be submitted includes:

Bank Name
Routing Code
SWIFT BIC
Bank Address

The API will then return:

Detailed bank information to help populate required fields.
Narrowed results due to its multiple criteria search capability in a single request.

Benefits:

Enables an intuitive, dynamic user experience.
Improves accuracy by helping users select the correct bank from potential matches.
Reduces friction and manual input by auto-filling bank details with validated data.

“Cambridge Mercantile” and “AFEX” and “Associated Foreign Exchange” and “Corpay” are names that may be used for Corpay Cross-Border services (international payment solutions and risk management solutions) provided by certain affiliated entities, all using the “Corpay” brand. International payment solutions are provided in Australia through Cambridge Mercantile (Australia) Pty. Ltd.; in Canada through Cambridge Mercantile Corp.; in the United Kingdom through Cambridge Mercantile Corp. (UK) Ltd.; in Ireland and the European Economic Area through Associated Foreign Exchange Ireland Ltd.; in Jersey through AFEX Offshore Ltd.; in New Zealand through Corpay (NZ) Limited; in Singapore through Associated Foreign Exchange (Singapore) Pte. Ltd. and in the United States through Cambridge Mercantile Corp. (U.S.A.). Risk management solutions are provided in Australia through Cambridge Mercantile (Australia) Pty. Ltd.; in Canada through Cambridge Mercantile Corp.; in the United Kingdom through Cambridge Mercantile Risk Management (UK) Ltd.; in Ireland and the European Economic Area through AFEX Markets Europe Ltd.; in Jersey through AFEX Offshore Ltd.; in New Zealand through Corpay (NZ) Limited; in Singapore through Associated Foreign Exchange (Singapore) Pte. Ltd. and in the United States through Cambridge Mercantile Corp. (U.S.A.). Please refer to http://cross-border.corpay.com/brochure-disclaimers for important terms and information.

Corpay Cross-Border SolutionsAPI Resources

API Release Notes and Upcoming Changes

Corpay Cross-Border has launched a new developer portal which contains a variety of guides and resources, as well as our API documentation. The purpose of the portal is to further support our partners who are integrated (or in the process of integrating) with our API suite.

You can access the new developer portal and API documentation via the direct links below:

Corpay’s Postman collection is still available for you to download all our API endpoints to your own instance of Postman. The Postman documentation link can be found within the developer portal.

*Have feedback or thoughts on what you would like to see on this new portal? Then please don’t hesitate to share your suggestions with technicalsales@corpay.com in which all feedback is welcome!

Region & Zip Enforcement (US & CA)

To comply with updated FINTRAC and related regulatory requirements, Corpay Cross-Border must ensure that valid region and ZIP/postal code information is included for both bank and beneficiary addresses in payments made to the U.S. and Canada.

What Does This Mean for You?

API Release Notes

May 2025

Beneficiary & Bank Region Enforcement

Further Credit (FFC)

SWIFT GPI v5 Update

Validate API Endpoint

Beneficiary Address Lines – PO Box Update

Onboarding API Documentation Update

Partner-Level Token Documentation Update

Token Endpoint – Error Response Update

We have updated the POST Partner and POST Client 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.You can find an example of the update below:

Mass Payment – Tracker Ids

Authentication Retrieval API

Onboarding API

What value does onboarding API provide to partners?

Automated APIs eliminate the manual process of submitting requests, increases efficiency, and expedites the process resulting in reduced time to revenue for partners.

Consistent and accurate onboarding requests from different partners ensure improved SLA between Corpay and our Partners as well as between Partners and their downstream clients.

The automated process increases the scalability of onboarding new clients for partners.

Partners will have access to up-to-date onboarding Terms and Conditions (T&C), thus ensuring their downstream clients comply and submit requests based on the most recent requirements.

With our onboarding APIs, partners will have access to a faster and more streamlined process to onboard their downstream clients thus improving their customer onboarding experience.

You can find the supporting Postman API documentation to all the new Onboarding API endpoints below:

Current status: North America is live, other global jurisdictions currently in Beta.

Push Notifications

Benefits to Push Notifications

With instant notifications and increased data visibility, you can improve your customer experience by being informed about the data that matters to you and your client.

Events covered under push notifications via webhooks:

Payments GPS

— Payment Accepted— Payment Processed— Payment Tracking Info Received— Payment Processed Non-Swift

Onboarding

— Account Approved

Current status: Testing is in progress on Beta environment, with our partners. Full Rollout is expected in Jan 2024.

Upcoming Updates

ISO20022

SWIFT’s Migration: SWIFT began its migration to ISO 20022 for Cross-Border payments in March 2023, with a coexistence period in place until November 2025.

Domestic Implementations: Various countries are adopting ISO 20022 for their domestic payment systems, each with specific timelines and requirements.

Why Is ISO 20022 Important?The adoption of ISO 20022 brings several significant benefits:

Enhanced Data Quality: The structured format allows for more precise information to travel with the payment, reducing errors and ambiguities in processing.

Improved Compliance: More detailed data can result in better monitoring and compliance with regulations, aiding in the fight against financial crimes.

Operational Efficiency: Standardization across systems leads to streamlined processes and reduced operational costs.

Global Interoperability: A common messaging standard facilitates smoother Cross-Border transactions, benefiting the wider international trade and finance community.

Innovation Enablement: Rich data opens doors for the development of more advanced analytics, AI applications, and improved customer experience.

As part of our continued commitment to payment modernization and global compliance, Corpay is also introducing enhancements aligned with ISO 20022 standards. These updates affect both our UI platform and API endpoints, providing richer data structures and a more standardized experience.

MT Field MT103

MX Field pacs.008

Description

:50: – Ordering Customer

<UltmtDbtr> or <Ddtr>

Sender’s account, name and address

:52: - Ordering Institution

<DbtrAgt>

Sender’s Bank

:59: - Beneficiary

<Cdtr> and <CdtrAcct>

Beneficiary account, name and address

:70: - Remittance info

<RmtInf>

Remittance Information and / or Purpose of payment

:72: - Sender to Receiver info

<InstrForNxtAgt> or <InstrForCdtrAgt>

Additional Instructions for processing

Purpose of Payment Enforcement

Enforcement TimelineThis validation is already enforced for all new clients and partners recently onboarded with Corpay. For existing partners, enforcement will begin in approx. 90 days, with deployment planned for the week commencing August 25th, 2025.

Next StepsWe have identified which existing partners are currently submitting invalid POP values and will be reaching out directly to support you with this update.

Currency Edits on Existing Bene Template

Enforcement TimelineThis change will be enforced in approx. 90 days, with deployment planned for the week commencing August 25th, 2025.

Additional Webhooks

One of the key pieces of feedback we received from our partners in last year’s survey was the desire to expand our webhook (push notification) capabilities. We’re therefore pleased to share that, as part of our Q2 development roadmap, we are introducing two new webhook subscription types:

Interested in early access?If you’d like to be one of our pilot clients and gain early access to these webhook features, please reach out to your Corpay Account Manager.

Onboarding API

Forward ‘Accept Terms’ API Endpoint Deprecation

New IP Address Range

Corpay Cross-Border Solutions
API Resources

We have updated the POST Partner and POST Client 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.

You can find an example of the update below:

— Payment Accepted
— Payment Processed
— Payment Tracking Info Received
— Payment Processed Non-Swift

Why Is ISO 20022 Important?

The adoption of ISO 20022 brings several significant benefits:

MT Field
MT103

MX Field
pacs.008

Enforcement Timeline

This validation is already enforced for all new clients and partners recently onboarded with Corpay. For existing partners, enforcement will begin in approx. 90 days, with deployment planned for the week commencing August 25th, 2025.

Next Steps

We have identified which existing partners are currently submitting invalid POP values and will be reaching out directly to support you with this update.

Enforcement Timeline

This change will be enforced in approx. 90 days, with deployment planned for the week commencing August 25th, 2025.

One of the key pieces of feedback we received from our partners in last year’s survey was the desire to expand our webhook (push notification) capabilities.

We’re therefore pleased to share that, as part of our Q2 development roadmap, we are introducing two new webhook subscription types:

Interested in early access?

If you’d like to be one of our pilot clients and gain early access to these webhook features, please reach out to your Corpay Account Manager.

SWIFT / BIC codes are used to identify specific banking institutions and are considered key validation fields for cross-border payments.

Corpay strongly recommends including SWIFT/BIC on all wire payments.

Beneficiary Rules (Template Guide)

The GET Beneficiary Rules endpoint allows partners to retrieve the required data fields for creating beneficiary templates and initiating payments. Requirements are based on: