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.

Postman Documentation Updates

In order to keep our existing and future integrated partners up to date with all the latest Corpay
Cross-Border API enhancements and features, we’ve now added a “What’s New?” section on our Postman documentation.



Our What’s New section will be frequently updated to inform our partners of any new and exciting features/enhancements that have been deployed to the Cross-Border API Suite v.18. It will also include links that take you directly to the corresponding technical specification, allowing you to begin reviewing and integrating any desired updates.



You can find our public facing Cross-Border API documentation v.18 here:







As always, if you would like to learn more about any of our recently deployed updates, then please don’t hesitate to reach out to your Corpay account manager or technicalsales@corpay.com.

MARKET ANALYSES
RESOURCES
PRIVACY POLICY
LEGAL & REGULATORY
CONTACT US

PRIVACY POLICY          LEGAL & REGULATORY          MARKET ANALYSES          RESOURCES          CONTACT US

“Cambridge Global Payments” and “AFEX” are trading names that may be used for the international payment solutions and risk management solutions provided by certain affiliated entities using the brand “Corpay”. International payment solutions are provided in Australia through Cambridge Mercantile (Australia) Pty. Ltd.; in Canada through Cambridge Mercantile Corp.; in Switzerland through Associated Foreign Exchange (Schweiz) AG; in the United Kingdom through Cambridge Mercantile Corp. (UK) Ltd.; in Ireland and the European Economic Area on a cross-border basis through Associated Foreign Exchange Ireland Ltd.; in Jersey and the Channel Islands through AFEX Offshore Ltd.; 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 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 on a cross-border basis through AFEX Markets Europe Ltd.; in Jersey and the Channel Islands through AFEX Offshore Ltd.; 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/disclaimers for important terms and information.

Upcoming Product Launches

Contact and Feedback

Webhooks

We are nearing the completion of our Webhook capabilities in which we will be able to send push notifications for different events you subscribe to. This means partners will no longer have to keep polling the Corpay API endpoints for new information or status updates (such as the status of a payment). We are looking at launching the product over the upcoming weeks following a soft pilot testing phase.

 
The first iteration of our Webhook launch will include push notifications for Payments GPS tracking and client onboarding account approval. Both notification types have been sought after by our partners, so we look forward to seeing the positive effect these additions will have to your Corpay API integration!

*Want to be part of Corpay’s early release/pilot scheme to test new API features before their wider production launch? Then please share your interest with technicalsales@corpay.com.

Upcoming API Changes

Corpay’s POST Accept Terms API endpoint has now been made obsolete and is no longer required for the Forward API workflow. A reminder of the change has been provided below:

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

Forward ‘Accept Terms’ API Endpoint Deprecation

API Documentation Updates

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!

Beneficiary & Bank Region Enforcement

To comply with updated FINTRAC requirements, Corpay Cross-Border will begin enforcing beneficiary and bank region validation when creating US, Canada, and Mexico beneficiary templates via the API. Specifically, 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.

 
IMPORTANT NOTE: Region validation will be enforced in our Beta API environment starting in December 2024, allowing partners to test and prepare for this change. Corpay will collaborate with partners identified as having the highest number of invalid region instances to ensure a smooth transition before full Production environment enforcement in Q1 2025.

Payment Tracking (SWIFT GPI)

Following the release of Corpay Cross-Border’s Payment Tracking (SWIFT GPI) API feature, partners will be able to trace the status and details of their wire payments sent via the SWIFT network. This has been a much sought-after feature whereby it will provide partners greater visibility into the status of their wire payments and more accurately communicate/display payment network messaging to their own clients.

Whilst Corpay’s Payment Tracking API services will retain existing capabilities, such as being able to view the SWIFT MT103 messaging of processed payments, the new tracking capabilities will provide a greater level of SWIFT messaging and status overview for a payment at each leg of its journey from Corpay to beneficiary (recipient). This is made possible by the new Payment Tracker ID that is returned for wire payments made via the API and searchable in our new Payment Tracking endpoints.

Payments GPS Benefits for integrated partners

Actionable transparency — Partners receive raw real-time data on each payment providing complete transparency on where the payment is, the latest status of the payment, reasons for rejection or delay, deductions by different correspondent banks, and the final amount delivered to the beneficiary.

Enhanced customer experience — With real-time raw data, partners can easily and quickly investigate any inquiry from their clients; helping them meet their SLA commitments for their downstream clients and build trust with their clients and their beneficiaries.

Self-serve and scalability — Partners can trace payment on demand with zero dependencies on Corpay’s team. Thus, the product improves their self-serve capability and allows them to scale international payments offering quickly.

Customization and flexibility in UX design — The product provides all the relevant data for payments, providing the flexibility to customize the payment tracking experience. Partners can present a simple payment journey with just the latest status of a payment to a comprehensive payment journey with every minute detail.

Trends in the New Economy

Through the lens of global market dynamics, Corpay is exploring what comes next, in terms of how our world, and the global economy, have changed, and how we navigate the associated uncertainty. Read our publication, updated regularly, to get an understanding of the trends shaping the future of global business and the payments business in particular.

Breaking Market News, Insights and Analyses

Be in the know, with our free and exclusive site delivering curated, FX-specific news, macroeconomic analysis, and market intelligence, on the world’s biggest economies

Subscribe to our market analysis program to gain insights into trends and developments in global currency markets, with market wires delivered right to your inbox

Downloadable Documents

Data Privacy & Security

Read more about the measures we take to protect the privacy and security of client data.

Fraud Awareness

Read more to learn about the best practices you can use to detect and mitigate fraud.

Master Currency Capabilities

Read more about our payment formatting guidelines and currency capabilities.

High Risk & Sanctioned Countries

Read more on the high risk and sanctioned countries list, as it applies to all transactions.

*Important to note: This feature is only available for viable payment currencies processed as 
wires via the SWIFT network. EFT, iACH and other local payment rails are currently not supported 
for payment tracking. 

You can find the supporting Postman API documentation to all the existing and new 
Payment Tracking API endpoints hyperlinked below:

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.

*Important to note: Corpay’s Compliance team and designated Technical Sales Consultant will work with each partner to validate what data points and supporting on-boarding documentation needs to be sent to Corpay via the onboarding API to ensure the successful approval and onboarding of a 
new client submission.

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

Check out the latest episode of our FX in Focus podcast! In Episode 46, Analyzing and Visualizing Currency Risk: Better decision-making in volatile markets, where we discuss how the capture and analysis of FX Risk exposure in forecasted cashflows can help you make better hedging decisions.

Analyzing and Visualizing Currency Risk: Better decision-making in volatile markets

Beneficiary Validation Best Practices

Corpay is dedicated to STP (straight-through processing) and seamless payment delivery. As part of Best Practice methodology, we regularly review beneficiary validation rules and exception handling metrics to mitigate manual repairs and ensure an exceptional payment life cycle.

We respectfully draw your attention to the following:

SWIFT/BIC Codes¹ (Mandatory for all Currencies — coming soon)

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.

IBAN²

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. 

¹ SWIFT codes, developed by Society for Worldwide Interbank Financial Telecommunication (SWIFT), form of international identification systems. BIC (Bank Identifier Code) refers to the institution .SWIFT and BIC are used to identify a specific bank during an international transaction.

 
² An IBAN is used to identify an individual account involved in an international transaction. The IBAN also acts as a method of verifying that transaction details are correct.

New IP Address Range

Corpay’s Web Application Firewall (WAF) provider has added new IP addresses to their range which our API partners may need to whitelist. Whilst we have had no reports of API connectivity issues following the IP address range additions, please find the new IP addresses for your reference below:

131.125.128.0/17 (131.125.128.1-131.125.255.254)

Upcoming API Changes

Mandatory SWIFT BIC Requirement

As detailed in the ‘Beneficiary Validation Best Practices’ section, Corpay will be enforcing SWIFT BIC as a mandatory field when creating beneficiaries as of December 4th 2023. 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}$.

Mandatory SWIFT BIC Requirement

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 4^th*. 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.

Payments GPS

Track and manage your payments from the moment they are booked, to when the payment leaves Corpay, to when it reaches the beneficiary’s bank account. To learn more, click here.

Push Notifications

Get access to instant notifications for your critical data events! Receive updates almost immediately on your data events without manual data poll requests for status updates.

With this simple but convenient feature, our push notifications have you covered, providing you with instant alerts on a payment and alerting you to newly onboarded clients, in each case almost immediately after it happens.

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.

1.   Reduce manual resources

2.   Real-time updates

3.   Improved customer experience

4.   Improved self-serve capability

5.   Secure and scalable

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

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

"The availability of GPS from Corpay has empowered our customers with in-depth knowledge about their payment deliverability. While we previously relied on basic Swift confirmations, we can now offer our customers granular and accurate insights. This has significantly boosted their confidence in using our platform for cross-border payments.

Internally, we are able to analyze corridor efficiencies and provide more intelligence to our customers on better deliverability options."

Steve Habegger
Co-founder & CTO
PayRecs

Read the success stories of Payments GPS:

"I wanted to share my experience with the Corpay Cross-Border portal, which has proven to be a valuable tool in my daily tasks. It really took no time to catch on.  
 
I can now easily track, in detail, when payments are entered and when they are completed. This has significantly simplified the reconciliation process on my end.  It also allows me to spot any potential issues ahead of time.
 
Additionally having access to up to date funding balance and transaction details is another excellent feature.

Great job Corpay team!"

Jeffrey Boyko
CFA, P.Eng
President, Chief Currency Strategist
Castle Currency Exchange, Inc.

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

Commercial Case:

Operational Case:

Corpay Cross-Border Solutions

API Resources

Authentication Retrieval API

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: 

Mass Payment – Tracker Ids

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:

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:

Beneficiary Address Lines – PO Box Update

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.

Onboarding API Documentation Update

Following feedback received from our partner via our Idea and Feedback portal, we have worked with our Compliance teams to update the POST Client Onboarding and POST Submit Onboarding Files mandatory/optional field details listed on our API documentation.

These minor updates should make it clearer for our partners as to what the mandatory onboarding fields in different countries/jurisdictions are which in turn will help their developers build out their own client onboarding interfaces.

Partner-Level Token Documentation Update

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.

Validate API Endpoint

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.

SWIFT GPI v5 Update

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.

API Release Notes

This section will provide additional details on Corpay’s recent API suite enhancements and feature deployments.

*Note: The endpoint URLs used throughout this section are of the Corpay Cross-Border v1.8 API Beta (Sandbox) Environment. These are shown for testing / illustration purposes only and are not representative of Production endpoints.

December 2024

What Does This Mean for You?

• 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).

Next Steps

• We have begun enabling this updated beneficiary creation validation logic on your Sandbox (Beta) environment so that you can test the required changes ahead of the Production deployment deadline. Supporting screenshots have been attached that showcase the updated logic as well as providing examples of the discussed API endpoints.

• To further help ensure you are passing valid region values for both US and CA beneficiary/bank address, please refer to our GET Region API endpoint that will allow you to retrieve the accepted region IDs and codes (to which you can use either). This will help ensure the data is accurate and compliant.

• Our GET Beneficiary Rules endpoint has also been updated in in our Sandbox environment to return the accepted Reg-Ex for US and CA address zip codes (such as structure, character length, etc.,).

• To confirm, this new validation enforcement will be in place for all new US and CA beneficiary template creation requests via the API. However, for reassurance, please know there will be no action needed on your side to mass update your existing beneficiary templates that may have invalid region and/or zip data.
  

We're Here to Help

Reiterating our above statement, we are here to assist you with this transition and ensure a smooth update to your integration. Most of you would have already been contacted by a Corpay representative to support you with testing. However, if that is not the case and you require help, please don’t hesitate to reach out to your account manager.