Corpay

Corpay Cross-Border API uses HATEOAS (Hypertext As The Engine Of Application State) framework. This means all response copy with and element `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

``` javascript
  {
    "content": {},
    "errors": [],
    "links": [
        {
            "rel": "self",
            "uri":   "https://crossborder.corpay.com/api/{endpoint}}",
            "method": {POST GET or PUT}
        }
    ]
  }

```

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.

# Common Terms

&lt;ul>&lt;li>&lt;p>Client Code - A unique 6-digit client identifier for each client account. Used in all endpoints as part of URL.&lt;/p>&lt;/li>&lt;li>&lt;p>Partner ID - Links multiple client accounts together. Used during authentication procedure.&lt;/p>&lt;/li>&lt;li>&lt;p>Payment - Outgoing cashflow to a beneficiary.&lt;/p>&lt;/li>&lt;li>&lt;p>Settlement - Incoming cashflow to Corpay.&lt;/p>&lt;/li>&lt;/ul>

# Base URL

The documentation for each endpoint displays the HTTP method and the end path. Before you submit the request, you need to prepend the base path to get the full resource URL. All endpoints referenced in the documentation require the following base path: [https://https://crossborder.corpay.com](https://https://crossborder.corpay.com).

**Note:** Depending on the stage of your implementation, the base path may be slightly different. For staging, pre-production, QA, and testing, use [https://crossborder.beta.corpay.com](https://crossborder.beta.corpay.com) to point to the Beta environment.

Curly braces are used as a placeholder and indicate the type of value that you need to supply. For instance, where you see {clientCode} in the resource, you need to replace that string with your client code.

For example, in the documentation, endpoints look similar to this:

`GET /api/{clientCode}/0/benes/{beneID}`

When you add the base path, your client code, and any parameters, the result is a well-formed REST URL that looks something like this:

`GET https://crossborder.corpay.com/api/123456/0/benes/jsmith321`

# Response Codes

Most of the endpoints include examples for both successful and unsuccessful responses. In the Example Request, click the downward arrow beside the response code to view additional examples.

Corpay Cross-Border uses conventional HTTP response codes to indicate the success or failure of an API request.

&lt;table>&lt;tbody>&lt;tr>&lt;th>Response Code&lt;/th>&lt;th>Description&lt;/th>&lt;/tr>&lt;tr>&lt;td>2&lt;i>xx&lt;/i>&lt;/td>&lt;td>Success.&lt;/td>&lt;/tr>&lt;tr>&lt;td>4&lt;i>xx&lt;/i>&lt;/td>&lt;td>&lt;p>Client error. This is usually due to missing or incorrect information, for example, a missing or incorrect parameter or value.&lt;/p>&lt;ul>&lt;li>&lt;p>401 - Authorization issue. This usually means that the authorization token has expired and you need to refresh it.&lt;/p>&lt;/li>&lt;li>&lt;p>410 - Rate resource expired. Due to currency fluctations, quotes are valid for a very limited period of time. When you get a 410 error, it means that the rate resource you're trying to use has expired and you need to generate a new quote.&lt;/p>&lt;/li>&lt;ul>&lt;/ul>&lt;/ul>&lt;/td>&lt;/tr>&lt;tr>&lt;td>5&lt;i>xx&lt;/i>&lt;/td>&lt;td>Server error. If the error persists, contact Corpay Tier 2 support.&lt;/td>&lt;/tr>&lt;/tbody>&lt;/table>

Introduction

Getting Started

<p class="slate-p " >Each endpoint in the documentation shows the HTTP method and the relative path. To form the full URL, prepend the base path -  <a href="https://https://crossborder.corpay.com" target="_self"><code class="slate-code">https://crossborder.corpay.com</code></a>.</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=warning ><div class="callout-icon"><svg width="18" height="16" viewBox="0 0 18 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.916637 15.5009C0.791637 15.5009 0.683998 15.4732 0.59372 15.4176C0.503443 15.362 0.430526 15.2857 0.37497 15.1884C0.319415 15.0912 0.288165 14.9905 0.28122 14.8864C0.274276 14.7822 0.305526 14.6745 0.37497 14.5634L8.4583 0.605103C8.52775 0.493991 8.60761 0.41413 8.69789 0.365519C8.78816 0.316908 8.88886 0.292603 8.99997 0.292603C9.11108 0.292603 9.21178 0.316908 9.30205 0.365519C9.39233 0.41413 9.47219 0.493991 9.54164 0.605103L17.625 14.5634C17.6944 14.6745 17.7257 14.7822 17.7187 14.8864C17.7118 14.9905 17.6805 15.0912 17.625 15.1884C17.5694 15.2857 17.4965 15.362 17.4062 15.4176C17.3159 15.4732 17.2083 15.5009 17.0833 15.5009H0.916637ZM1.99997 14.2509H16L8.99997 2.1676L1.99997 14.2509ZM9.0833 13.0634C9.26386 13.0634 9.41316 13.0044 9.53122 12.8864C9.64928 12.7683 9.7083 12.619 9.7083 12.4384C9.7083 12.2579 9.64928 12.1086 9.53122 11.9905C9.41316 11.8725 9.26386 11.8134 9.0833 11.8134C8.90275 11.8134 8.75344 11.8725 8.63539 11.9905C8.51733 12.1086 8.4583 12.2579 8.4583 12.4384C8.4583 12.619 8.51733 12.7683 8.63539 12.8864C8.75344 13.0044 8.90275 13.0634 9.0833 13.0634ZM9.0833 10.7509C9.26386 10.7509 9.41316 10.6919 9.53122 10.5739C9.64928 10.4558 9.7083 10.3065 9.7083 10.1259V6.70927C9.7083 6.52871 9.64928 6.37941 9.53122 6.26135C9.41316 6.1433 9.26386 6.08427 9.0833 6.08427C8.90275 6.08427 8.75344 6.1433 8.63539 6.26135C8.51733 6.37941 8.4583 6.52871 8.4583 6.70927V10.1259C8.4583 10.3065 8.51733 10.4558 8.63539 10.5739C8.75344 10.6919 8.90275 10.7509 9.0833 10.7509Z" fill="#F1C21B"></path></svg></div><div ><p class="slate-p slate-indent-0" style="0px">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"><code class="slate-code">https://crossborder.beta.corpay.com</code></a> </p></div></div><div class="card-box without-icon" style="width:100%;"><div ><h3 class="slate-h3 " >VALID REST URL</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Curly braces indicate placeholders for values you must provide. For example, replace <code class="slate-code">{clientCode}</code> with your actual client code.</div></li><li class="slate-li " ><div style="position:relative">Example endpoint - <code class="slate-code">GET /api/{clientCode}/0/benes/{beneID}</code></div></li><li class="slate-li " ><div style="position:relative">After adding the base path, client code, and the required parameters, the complete URL looks like this - <code class="slate-code">GET https://crossborder.corpay.com/api/123456/0/benes/jsmith321</code></div></li></ul></div></div><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

Base URL

Our RESTful API suite employs an OAuth2 framework which consists of a two part flow that involves exchanging a 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 or the Client (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. 

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 partner-level, there is no need to pass anything through "CMG-AccessToken" for the partner-level.
&lt;br />

----
&lt;br />

##### AUTHENTICATION ERRORS

&lt;table style="width:100%">
  &lt;tr>
    &lt;th align="left">Error Code&lt;/th>
    &lt;th align="left">Description&lt;/th>
  &lt;/tr>
  &lt;tr>
    &lt;td>400 Bad Request - Invalid value for audience&lt;/td>
    &lt;td>JWT audience (aud) value of 'cambridgefx' was expected.  Make sure that the audience ("aud") is set to "cambridgefx" (in the JWT claimset)&lt;/td>
  &lt;/tr>
  &lt;tr>
    &lt;td>400 Bad Request - 'exp' token is set too far into the future&lt;/td>
    &lt;td>This error is the result of setting the token too far into the future. The threshold is approximately 24 hours after issue.&lt;/td>
  &lt;/tr>
  &lt;tr>
    &lt;td>400 Bad Request - Invalid Issuer (either Partner or User)&lt;/td>
    &lt;td>User not found or partner access not configured. Check the "error_description" parameter for more information.&lt;/td>
  &lt;/tr>
  &lt;tr>
    &lt;td>400 Bad Request - Invalid signature key&lt;/td>
    &lt;td>The auth key or signature must be current; otherwise the token will not be signed properly.&lt;/td>
  &lt;/tr>
  &lt;tr>
    &lt;td>400 Bad Request - JWT Token is expired&lt;/td>
    &lt;td>As a general rule, use 'time + 20 minutes' as your expiry date/time.&lt;/td>
  &lt;/tr>
&lt;/table>


2-Token Auth

Sample payload for the JWT token generation:

```
{
"iss": "test",
"iat": 1480103915,
"exp": 1480105116,
"aud": "cambridgefx",
"sub": ""
}

```

[This link](http://jwtbuilder.jamiekurtz.com/) has a form to generate JWT 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:

*   Algorithm has to be HS256.
*   Assertion needs to regenerated as it has expiry time.
*   Assertion value is an encoded JWT token that contain security key provided by Corpay.
*   `iss` is the Corpay-provided partner ID.

Partner-level Token Login

The authentication on the Client-level is similar to the authentication process at the partner-level. 
Two key differences in the JWT construction:
&lt;ul>
&lt;li>&lt;code>access_code&lt;/code> from Partner Auth goes in the header of this API.&lt;/li>
&lt;li>API username is the `iss` in the JWT token. &lt;/li>
&lt;/ul>

The `access_code` granted at the Client-level will be the session token for all subsequent calls in the current user session. 

Expiry of the `access_code` can accomodate different use cases.

Client-level Token Login

<h1 class="slate-h1 " ></h1><p class="slate-p slate-indent-0" style="0px">Most endpoints include examples of both successful and unsuccessful responses. In the Response window, click a status code to view the example.</p><p class="slate-p slate-indent-0" style="0px">Corpay Cross-Border follows standard HTTP status codes to indicate request success or failure.</p><p class="slate-p " ></p><p class="slate-p " ><p class="slate-p " ></p></p><p class="slate-p " ></p><p class="slate-p " ></p>

Response Codes

Test API in Sandbox

Corpay Cross-Border API Documentation v1.8

How To

Production

Sandbox

<div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=success ><div class="callout-icon"><svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M7.77116 10.8968L5.72949 8.8551C5.60449 8.7301 5.45171 8.6676 5.27116 8.6676C5.0906 8.6676 4.93088 8.73705 4.79199 8.87594C4.6531 9.01482 4.58366 9.17455 4.58366 9.3551C4.58366 9.53566 4.6531 9.68844 4.79199 9.81344L7.33366 12.3551C7.45866 12.4801 7.60449 12.5426 7.77116 12.5426C7.93783 12.5426 8.08366 12.4801 8.20866 12.3551L13.2087 7.3551C13.3337 7.2301 13.3927 7.07732 13.3857 6.89677C13.3788 6.71621 13.3128 6.56344 13.1878 6.43844C13.0628 6.29955 12.9066 6.2301 12.7191 6.2301C12.5316 6.2301 12.3684 6.29955 12.2295 6.43844L7.77116 10.8968ZM9.00033 17.3343C7.81977 17.3343 6.72255 17.1225 5.70866 16.6989C4.69477 16.2752 3.81283 15.6884 3.06283 14.9384C2.31283 14.1884 1.72602 13.3065 1.30241 12.2926C0.878798 11.2787 0.666992 10.1815 0.666992 9.00094C0.666992 7.83427 0.878798 6.74399 1.30241 5.7301C1.72602 4.71621 2.31283 3.83427 3.06283 3.08427C3.81283 2.33427 4.69477 1.74399 5.70866 1.31344C6.72255 0.88288 7.81977 0.667603 9.00033 0.667603C10.167 0.667603 11.2573 0.88288 12.2712 1.31344C13.285 1.74399 14.167 2.33427 14.917 3.08427C15.667 3.83427 16.2573 4.71621 16.6878 5.7301C17.1184 6.74399 17.3337 7.83427 17.3337 9.00094C17.3337 10.1815 17.1184 11.2787 16.6878 12.2926C16.2573 13.3065 15.667 14.1884 14.917 14.9384C14.167 15.6884 13.285 16.2752 12.2712 16.6989C11.2573 17.1225 10.167 17.3343 9.00033 17.3343ZM9.00033 16.0843C11.0142 16.0843 12.6982 15.4072 14.0524 14.053C15.4066 12.6989 16.0837 11.0148 16.0837 9.00094C16.0837 6.98705 15.4066 5.30302 14.0524 3.94885C12.6982 2.59469 11.0142 1.9176 9.00033 1.9176C6.98644 1.9176 5.30241 2.59469 3.94824 3.94885C2.59408 5.30302 1.91699 6.98705 1.91699 9.00094C1.91699 11.0148 2.59408 12.6989 3.94824 14.053C5.30241 15.4072 6.98644 16.0843 9.00033 16.0843Z" fill="#06837A"></path></svg></div><div ><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">In this guide, you will find helpful instructions for common tasks like generating API keys and more.</strong></p></div></div><p class="slate-p slate-indent-0" style="0px">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.</p><p class="slate-p " >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 <code class="slate-code">SELF</code> 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.<div class="slate-div"></div></p><p class="slate-p " ><div class="slate-div"></div></p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-javascript keep-markup drop-tokens"><div class="slate-code_line">  {</div><div class="slate-code_line">    &quot;content&quot;: {},</div><div class="slate-code_line">    &quot;errors&quot;: [],</div><div class="slate-code_line">    &quot;links&quot;: [</div><div class="slate-code_line">        {</div><div class="slate-code_line">            &quot;rel&quot;: &quot;self&quot;,</div><div class="slate-code_line">            &quot;uri&quot;:   &quot;https://crossborder.corpay.com/api/{endpoint}}&quot;,</div><div class="slate-code_line">            &quot;method&quot;: {POST GET or PUT}</div><div class="slate-code_line">        }</div><div class="slate-code_line">        ]</div><div class="slate-code_line">  }</div><div class="slate-code_line"></div></code></pre></div><h1 class="slate-h1 " ><span style="background-color:rgb(255, 255, 255);color:rgb(33, 33, 33)"> </span></h1><p class="slate-p " ></p><p class="slate-p " ></p>

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 

 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.

<p class="slate-p slate-indent-0" style="0px">To begin, you will need to generate an access token to allow you to reach all other API endpoints. <a href="https://developer.crossborder.corpay.com/howto/2-token-auth" target="">See 2-Token Auth</a>. </p><div class="card-box" style="width:60%;"><svg width="32" height="32" viewBox="0 0 24 24" fill="none" class="icon-style" xmlns="http://www.w3.org/2000/svg"> <g clipPath="url(#clip0_2631_4454)"> <path d="M17.0002 0H7.00015C5.67456 0.00158786 4.40371 0.528882 3.46637 1.46622C2.52903 2.40356 2.00174 3.67441 2.00015 5V20C2.00015 21.0609 2.42158 22.0783 3.17173 22.8284C3.92187 23.5786 4.93929 24 6.00015 24H17.0002C18.3257 23.9984 19.5966 23.4711 20.5339 22.5338C21.4713 21.5964 21.9986 20.3256 22.0002 19V5C21.9986 3.67441 21.4713 2.40356 20.5339 1.46622C19.5966 0.528882 18.3257 0.00158786 17.0002 0V0ZM20.0002 5V16H8.00015V2H17.0002C17.7958 2 18.5589 2.31607 19.1215 2.87868C19.6841 3.44129 20.0002 4.20435 20.0002 5ZM6.00015 2.172V16C5.29778 15.9994 4.60776 16.1847 4.00015 16.537V5C4.00024 4.37969 4.19261 3.77466 4.55079 3.2682C4.90896 2.76175 5.41532 2.37877 6.00015 2.172ZM17.0002 22H6.00015C5.46972 22 4.96101 21.7893 4.58594 21.4142C4.21087 21.0391 4.00015 20.5304 4.00015 20C4.00015 19.4696 4.21087 18.9609 4.58594 18.5858C4.96101 18.2107 5.46972 18 6.00015 18H20.0002V19C20.0002 19.7956 19.6841 20.5587 19.1215 21.1213C18.5589 21.6839 17.7958 22 17.0002 22Z" fill="#374957" /> </g> <defs> <clipPath id="clip0_2631_4454"> <rect width="32" height="32" fill="white" /> </clipPath> </defs> </svg><div ><h3 class="slate-h3 " >Supporting Information</h3><p class="slate-p " >Access up-to-date details on supported currencies, countries, and regions, to help you validate and configure your transactions accurately and ensure compliance with Corpay’s API requirements. </p><p class="slate-p " ><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Current API Version</strong> - <code class="slate-code">1.8</code></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Supported Currencies</strong> - Use <code class="slate-code">GET /api/payCurrencies?product=Bene</code> to retrieve valid values.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Supported Countries</strong> - Use <code class="slate-code">GET /api/countries</code> to retrieve valid values.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Supported States/Regions</strong> - Use <code class="slate-code">GET /api/regions?Country=ISO2 country code</code> to retrieve valid values. </div></li></ul></p></div></div><div class="card-box" style="width:60%;"><svg width="32" height="32" viewBox="0 0 24 24" fill="none" class="icon-style" xmlns="http://www.w3.org/2000/svg"> <g clipPath="url(#clip0_2631_4457)"> <path d="M20.1371 24C19.7672 23.999 19.4011 23.9247 19.0601 23.7813C18.719 23.638 18.4097 23.4285 18.1501 23.165L12.0001 17.051L5.85012 23.169C5.45515 23.5697 4.94861 23.8422 4.39654 23.9508C3.84447 24.0594 3.27247 23.9992 2.75512 23.778C2.23264 23.5678 1.78567 23.205 1.47258 22.7369C1.15949 22.2688 0.994841 21.7171 1.00012 21.154V5C1.00012 3.67392 1.52691 2.40215 2.46459 1.46447C3.40227 0.526784 4.67404 0 6.00012 0L18.0001 0C18.6567 0 19.3069 0.129329 19.9135 0.380602C20.5202 0.631876 21.0714 1.00017 21.5357 1.46447C22 1.92876 22.3683 2.47996 22.6195 3.08658C22.8708 3.69321 23.0001 4.34339 23.0001 5V21.154C23.0057 21.7167 22.8417 22.268 22.5293 22.7361C22.217 23.2041 21.7709 23.5672 21.2491 23.778C20.8969 23.9253 20.5189 24.0008 20.1371 24ZM6.00012 2C5.20447 2 4.44141 2.31607 3.8788 2.87868C3.31619 3.44129 3.00012 4.20435 3.00012 5V21.154C2.99976 21.3206 3.04879 21.4836 3.14102 21.6224C3.23325 21.7612 3.36455 21.8695 3.51831 21.9337C3.67208 21.9979 3.84143 22.0151 4.00496 21.9831C4.1685 21.9512 4.31888 21.8714 4.43712 21.754L11.3001 14.933C11.4875 14.7468 11.7409 14.6422 12.0051 14.6422C12.2693 14.6422 12.5228 14.7468 12.7101 14.933L19.5651 21.752C19.6834 21.8694 19.8338 21.9492 19.9973 21.9811C20.1608 22.0131 20.3302 21.9959 20.4839 21.9317C20.6377 21.8675 20.769 21.7592 20.8612 21.6204C20.9535 21.4816 21.0025 21.3186 21.0021 21.152V5C21.0021 4.20435 20.6861 3.44129 20.1234 2.87868C19.5608 2.31607 18.7978 2 18.0021 2H6.00012Z" fill="#374957" /> </g> <defs> <clipPath id="clip0_2631_4457"> <rect width="32" height="32" fill="white" /> </clipPath> </defs> </svg><div ><h3 class="slate-h3 " >Key identifiers and concepts used across Corpay Cross-Border APIs.</h3><p class="slate-p " ><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Client Code</strong> - A unique 6-digit client identifier for each client account. Used in all endpoints as part of the URL.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Partner ID</strong> - Links multiple client accounts together. Used during the authentication procedure.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Client Integration ID</strong>- Unique beneficiary ID that you can use in other endpoints.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Tracker ID</strong> - The unique tracker identifier assigned to a payment transaction.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Payment </strong>- Outgoing cashflow to a beneficiary.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Settlement </strong>- Incoming cashflow to Corpay.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">MCA </strong>- Multi-Currency Accounts (Formerly known as FXBalance/CLIAB)</div></li></ul></p></div></div><p class="slate-p slate-indent-0" style="0px"></p><p class="slate-p " ></p><p class="slate-p " ><p class="slate-p " ></p><p class="slate-p " ></p></p>

To begin, you will need to generate an access token to allow you to reach all other API endpoints. 

<p class="slate-p " >Each endpoint in the documentation shows the HTTP method and the relative path. To form the full URL, prepend the base path -  <a href="https://https://crossborder.corpay.com" target="_self"><code class="slate-code">https://crossborder.corpay.com</code></a>.</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >The endpoint URLs <a href="https://crossborder.beta.corpay.com" target="_self"><code class="slate-code">https://crossborder.beta.corpay.com</code></a> used in the documentation 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. </p></div></div><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=warning ><div class="callout-icon"><svg width="18" height="16" viewBox="0 0 18 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.916637 15.5009C0.791637 15.5009 0.683998 15.4732 0.59372 15.4176C0.503443 15.362 0.430526 15.2857 0.37497 15.1884C0.319415 15.0912 0.288165 14.9905 0.28122 14.8864C0.274276 14.7822 0.305526 14.6745 0.37497 14.5634L8.4583 0.605103C8.52775 0.493991 8.60761 0.41413 8.69789 0.365519C8.78816 0.316908 8.88886 0.292603 8.99997 0.292603C9.11108 0.292603 9.21178 0.316908 9.30205 0.365519C9.39233 0.41413 9.47219 0.493991 9.54164 0.605103L17.625 14.5634C17.6944 14.6745 17.7257 14.7822 17.7187 14.8864C17.7118 14.9905 17.6805 15.0912 17.625 15.1884C17.5694 15.2857 17.4965 15.362 17.4062 15.4176C17.3159 15.4732 17.2083 15.5009 17.0833 15.5009H0.916637ZM1.99997 14.2509H16L8.99997 2.1676L1.99997 14.2509ZM9.0833 13.0634C9.26386 13.0634 9.41316 13.0044 9.53122 12.8864C9.64928 12.7683 9.7083 12.619 9.7083 12.4384C9.7083 12.2579 9.64928 12.1086 9.53122 11.9905C9.41316 11.8725 9.26386 11.8134 9.0833 11.8134C8.90275 11.8134 8.75344 11.8725 8.63539 11.9905C8.51733 12.1086 8.4583 12.2579 8.4583 12.4384C8.4583 12.619 8.51733 12.7683 8.63539 12.8864C8.75344 13.0044 8.90275 13.0634 9.0833 13.0634ZM9.0833 10.7509C9.26386 10.7509 9.41316 10.6919 9.53122 10.5739C9.64928 10.4558 9.7083 10.3065 9.7083 10.1259V6.70927C9.7083 6.52871 9.64928 6.37941 9.53122 6.26135C9.41316 6.1433 9.26386 6.08427 9.0833 6.08427C8.90275 6.08427 8.75344 6.1433 8.63539 6.26135C8.51733 6.37941 8.4583 6.52871 8.4583 6.70927V10.1259C8.4583 10.3065 8.51733 10.4558 8.63539 10.5739C8.75344 10.6919 8.90275 10.7509 9.0833 10.7509Z" fill="#F1C21B"></path></svg></div><div ><p class="slate-p slate-indent-0" style="0px">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"><code class="slate-code">https://crossborder.beta.corpay.com</code></a> </p></div></div><div class="card-box without-icon" style="width:100%;"><div ><h3 class="slate-h3 " >VALID REST URL</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Curly braces indicate placeholders for values you must provide. For example, replace <code class="slate-code">{clientCode}</code> with your actual client code.</div></li><li class="slate-li " ><div style="position:relative">Example endpoint - <code class="slate-code">GET /api/{clientCode}/0/benes/{beneID}</code></div></li><li class="slate-li " ><div style="position:relative">After adding the base path, client code, and the required parameters, the complete URL looks like this - <code class="slate-code">GET https://crossborder.corpay.com/api/123456/0/benes/jsmith321</code></div></li></ul></div></div><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

Each endpoint in the documentation shows the HTTP method and the relative path. To form the full URL, prepend the base path -  

<p class="slate-p " >Our RESTful API suite employs an OAuth2 framework which consists of a two-part flow that involves exchanging an HS256-signed JWT token for a “CMG-AccessToken”.</p><p class="slate-p " >The partner-level and the client-level work in the following way: Given “Issuer” - either the name of the Partner or the Client (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 &quot;assertion&quot; field).</p><p class="slate-p " >When creating the token, the &quot;issued-at&quot; and the &quot;expiration&quot; should be current, and advisably set apart at an interval of 20 minutes, respectively.</p><p class="slate-p " >Once the call is placed, the response provides an &quot;access_code&quot; which will be submitted to the &quot;CMG-AccessToken&quot; 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 &quot;CMG-AccessToken&quot; for the partner-level.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><p class="slate-p " ></p><h5 class="slate-h5 " ></h5><p class="slate-p " ></p><p class="slate-p " >

</p><p class="slate-p " ></p>

Our RESTful API suite employs an OAuth2 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 or the Client (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.

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.

JWT audience (aud) value of 'cambridgefx' was expected. Make sure that the audience ("aud") is set to "cambridgefx" (in the JWT claimset).

400 Bad Request - Invalid value for audience

This error is the result of setting the token too far into the future. The threshold is approximately 24 hours after the issue.


400 Bad Request - 'exp' token is set too far into the future

User not found or partner access not configured. Check the "error_description" parameter for more information.

400 Bad Request - Invalid Issuer (either Partner or User)

The auth key or signature must be current; otherwise, the token will not be signed properlythat can't be charged for some reason.

400 Bad Request - Invalid signature key

As a general rule, use 'time + 20 minutes' as your expiry date/time.
API endpoint and parameters.

400 Bad Request - JWT Token is expired

<p class="slate-p " >Sample payload for the JWT token generation:</p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">&quot;iss&quot;: &quot;test&quot;,</div><div class="slate-code_line">&quot;iat&quot;: 1480103915,</div><div class="slate-code_line">&quot;exp&quot;: 1480105116,</div><div class="slate-code_line">&quot;aud&quot;: &quot;cambridgefx&quot;,</div><div class="slate-code_line">&quot;sub&quot;: &quot;&quot;</div><div class="slate-code_line">}</div><div class="slate-code_line"></div></code></pre></div><p class="slate-p " ><a href="http://jwtbuilder.jamiekurtz.com/" target="_self">This link</a> has a form to generate a token.</p><p class="slate-p " >For the token, you must be current between the window of the issue and the expiry (<code class="slate-code">iat</code> and <code class="slate-code">exp</code>, respectively) of the Unix-Timestamp.</p><h5 class="slate-h5 " ><strong class="slate-bold">IMPLEMENTATION NOTES:</strong></h5><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Algorithm has to be HS256.</div></li><li class="slate-li " ><div style="position:relative">Assertion needs to be regenerated as it has an expiry time.</div></li><li class="slate-li " ><div style="position:relative">Assertion value is an encoded JWT token that contains a security key provided by Corpay.</div></li><li class="slate-li " ><div style="position:relative"><code class="slate-code">iss</code> is the Corpay-provided partner ID.</div></li></ul></div></div><p class="slate-p " ></p><div class="slate-div"></div><div class="slate-div"></div><p class="slate-p " ></p><p class="slate-p " ></p>

Sample payload for the JWT token generation:

For the token, you must be current between the window of the issue and the expiry (

assertion

grant_type

Content-Type

access_code

token_type

expires_in

links

error

error_description

message

<p class="slate-p " >The authentication on the Client-level is similar to the authentication process at the partner-level.
Two key differences in the JWT construction:</p><p class="slate-p " ><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><code class="slate-code">access_code</code> from Partner Auth goes in the header of this API.</div></li><li class="slate-li " ><div style="position:relative">API username is the <code class="slate-code">iss</code> in the JWT token. </div></li></ul></p><p class="slate-p " >The <code class="slate-code">access_code</code> granted at the Client-level will be the session token for all subsequent calls in the current user session.</p><p class="slate-p " >Expiry of the <code class="slate-code">access_code</code> can accommodate different use cases.</p><div class="slate-div"></div><div class="slate-div"></div><p class="slate-p " ></p><p class="slate-p " ></p>

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

 granted at the Client-level will be the session token for all subsequent calls in the current user session.

CMG-AccessToken

<h1 class="slate-h1 " ></h1><p class="slate-p slate-indent-0" style="0px">Most endpoints include examples of both successful and unsuccessful responses. In the Response window, click a status code to view the example.</p><p class="slate-p slate-indent-0" style="0px">Corpay Cross-Border follows standard HTTP status codes to indicate request success or failure.</p><p class="slate-p " ></p><p class="slate-p " ><p class="slate-p " ></p></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

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.

The request was unacceptable, often due to missing or incorrect parameters or values.

This usually means that the authorization token has expired, and you need to refresh it

Due to currency fluctuation, quotes are valid for a very limited period of time. When you get a 410 error, it means that the rate resource you're trying to use has expired and you need to generate a new quote.

If the error persists, please contact Corpay Tier 2 support.

Sections