Acceleron FX API – Developer Guide

 

Overview

The Acceleron FX API provides financial institutions with a simple and efficient way to integrate foreign exchange (FX) services into their existing payments infrastructure. Designed for seamless integration with major core payment platforms, the API enables developers to quote, process, monitor, and manage international payments with minimal effort.

This guide will walk you through the API's key functionalities, authentication process, and how to start making requests.

---

 

Getting Started

 

1. Authentication & API Access

To access the API, you’ll need:

• A registered API key
• Submission of client IP addresses to connect to the system
• Originating bank information, including routing number and address
  

 

---

 

2. Core API Functionalities

The Acceleron FX API consists of several main components:

🔹 Quotes API – Get, lock, refresh, or cancel FX quotes

• Create a Quote (POST /quotes) – Request a live FX rate for a given amount and currency pair

• Lock Quote (POST /quotes/{quoteId}/lock) – Secure an exchange rate for a set duration

• Refresh Quote (POST /quotes/{quoteId}/refresh) – Get an updated rate if the original quote expires

• Cancel Quote (DELETE /quotes/{quoteId}) – Void an unused quote if allowed

🔹 Payments API – Create, approve, update, and track international payments

• Create a Payment (POST /payments) – Initiate an international payment 

• Update a Payment (PUT /payments/{paymentId}) – Modify an unprocessed payment

• Approve a Payment (POST /payments/{paymentId}/approve) – Authorize a pending payment

• Cancel a Payment (DELETE /payments/{paymentId}) – Revoke a payment before processing

 

---

 

3. API Workflow

A typical FX payment workflow involves the following steps:

1️⃣ Obtain an FX Quote – Request a real-time rate using POST /quotes

2️⃣ Lock or Refresh the Quote (if needed)

3️⃣ Create an International Payment using the quote ID (POST /payments)

4️⃣ Approve the Payment (POST /payments/{paymentId}/approve)

6️⃣ Cancel Payment (if necessary) before processing (DELETE /payments/{paymentId})

 

---

 

4. Error Handling & Best Practices

✅ Use proper authentication - A HTTP 403 error is returned when authentication details are incorrect.

✅ Check quote expiration – FX rates fluctuate, so ensure quotes are locked or refreshed before using them. Locking an expired quote will fail. Ensure that when calling the lock quote API endpoint that non-200 HTTP error codes are handled appropriately for failures.

✅  Checking for validation errors returned by creating and approving payments. Both of these API endpoints return errors for missing required fields and other country-specific requirements that fail validations.

✅ Handle API errors – The API returns structured error messages with HTTP status codes for debugging. All API endpoints have the potential to return an error status if an issue occurs. Please ensure that non-200 HTTP error codes are handled appropriately.

 

 

---

 

Next Steps

• Read the full API documentation for endpoint details

• Request API credentials to start testing in a sandbox environment

• Implement API integration to connect systems to the Acceleron Payments API

• Contact our support team for implementation assistance

 

 

---

API Flow

 

---

Common Request Headers (Required for all API endpoints)

Headers

Key	Type	Description
apiKey	string	Provided API Key
bankId	string	Bank ID (Routing Number) (Required) Example: 123456789

 

 

---

Quotes API

Create New Quote

Generate a foreign exchange quote for a payment.

Endpoint:

POST /quotes

Description:

This endpoint allows you to generate a foreign exchange (FX) quote for a payment, specifying the source and destination currencies and the amount.

Only beneficiaryAmount and beneficiaryCurrency are required for the Request Body; providing additional wire details up front can help optimize the quote.

Request Body

{   "beneficiaryAmount": 12345.67,   "beneficiaryCurrency": "EUR",   "originatorAmount": 76543.21,   "originatorCurrency": "CAD",   "details": {     "country": "US",     "originator": {       "name": "Jake Johnson",       "address": {         "address1": "555 South North Lane",         "address2": "Floor 5",         "city": "Springfield",         "state": "VA",         "postalCode": 47060,         "country": "US"       },       "type": "individual"     },     "beneficiary": {       "name": "Jake Johnson",       "address": {         "address1": "555 South North Lane",         "address2": "Floor 5",         "city": "Springfield",         "state": "VA",         "postalCode": 47060,         "country": "US"       },       "email": "beneficiary@example.com",       "phoneNumber": "111-111-1111",       "type": "individual"     }   } }

Response

Success Response (200 OK)

No JSON data is returned on a success (200 OK)

 

---

Lock Quote

Lock a foreign exchange quote to prevent it from expiring before payment.

Endpoint:

POST /quotes/{quoteId}/lock

Description:

This endpoint allows you to lock an FX quote, ensuring the exchange rate remains fixed for a specified duration before executing the payment.

Path Parameter

Parameter	Type	Description
quoteId	string	Unique identifier for the quote

Response

Success Response (200 OK)

Response Body

{     "id": 902068113,     "beneficiaryCurrency": "EUR",     "originatorAmountIsFixed": false,     "originatorAmount": 1138.60,     "beneficiaryAmount": 1000.00,     "exchangeRate": 1.1386,     "locked": true,     "revision": 1,     "valueDate": "2025-04-11" }

 

---

Refresh Quote

Refresh an expired or soon-to-expire foreign exchange quote.

Endpoint:

POST /quotes/{quoteId}/refresh

Description:

This endpoint allows you to refresh an FX quote to get the latest exchange rate while maintaining the same source and destination currencies and amount.

Path Parameter

Parameter	Type	Description
quoteId	string	Unique identifier for the quote

 

Response

Success Response (200 OK)

Response Body

{     "id": 902068113,     "beneficiaryCurrency": "EUR",     "originatorAmountIsFixed": false,     "originatorAmount": 1138.60,     "beneficiaryAmount": 1000.00,     "exchangeRate": 1.1386,     "locked": false,     "revision": 1,     "valueDate": "2025-04-11" }

 

 

---

Cancel Quote

Cancel a previously generated foreign exchange quote.

Endpoint:

DELETE /quotes/{quoteId}

Description:

This endpoint allows you to cancel a quote that is no longer needed. Quotes that have already expired or been used in a payment cannot be canceled.

Request

Path Parameter

Parameter	Type	Description
quoteId	string	Unique identifier for the quote

 

Response

No JSON data is returned on a success (200 OK)

 

---

 

Payments API

Create Payment

Initiate a new international payment using the Acceleron Payments API.

Endpoint:

POST /payments

Description:

This endpoint allows you to create an international payment by specifying the originator, beneficiary, and bank details. Originator Bank information is pre-populated by Acceleron based on client provided bank details.

Request

Request Body (JSON format) 

{   "originator": {     "name": "Jake Johnson",     "address": {       "address1": "555 South North Lane",       "address2": "Floor 5",       "city": "Springfield",       "state": "VA",       "postalCode": 47060,       "country": "US"     },     "type": "individual"   },   "originatorBankAccount": {     "accountNumber": "DE89370400440532013000",     }   },   "beneficiary": {     "name": "Jake Johnson",     "address": {       "address1": "555 South North Lane",       "address2": "Floor 5",       "city": "Springfield",       "state": "VA",       "postalCode": 47060,       "country": "US"     },     "email": "beneficiary@example.com",     "phoneNumber": "111-111-1111",     "type": "individual"   },   "beneficiaryBankAccount": {     "accountNumber": "DE89370400440532013000",     "bank": {       "name": "Jake Johnson",       "address": {         "address1": "555 South North Lane",         "address2": "Floor 5",         "city": "Springfield",         "state": "VA",         "postalCode": 47060,         "country": "US"       }     }   },   "amount": {     "currency": "USD",     "value": 1000.00   },   "paymentReference": "INV-202503",   "paymentMethod": "WIRE",   "callbackUrl": "https://yourapp.com/webhook/payment-status" }

 

Success Response (201 Created)

{   "id": 123456,   "quoteId": 123456,   "status": {     "approved": false,     "sent": false   },   "originator": {     "name": "Jake Johnson",     "address": {       "address1": "555 South North Lane",       "address2": "Floor 5",       "city": "Springfield",       "state": "VA",       "postalCode": 47060,       "country": "US"     },     "type": "individual"   },   "originatorBankAccount": {     "accountNumber": "DE89370400440532013000",     "bank": {       "name": "Originator Bank",       "address": {         "address1": "123 Bank St",         "address2": "Unit 11",         "city": "Springfield",         "state": "VA",         "postalCode": 47060,         "country": "US"       }     }   },   "beneficiary": {     "name": "Jake Johnson",     "address": {       "address1": "555 South North Lane",       "address2": "Floor 5",       "city": "Springfield",       "state": "VA",       "postalCode": 47060,       "country": "US"     },     "email": "beneficiary@example.com",     "phoneNumber": "111-111-1111",     "type": "individual"   },   "beneficiaryBankAccount": {     "accountNumber": "DE89370400440532013000",     "bank": {       "name": "Beneficiary Bank",       "address": {         "address1": "555 South North Lane",         "address2": "Floor 5",         "city": "Springfield",         "state": "VA",         "postalCode": 47060,         "country": "US"       }     }   },   "intermediaryBankAccount": {     "accountNumber": "DE89370400440532013000",     "bank": {       "name": "Intermediary Bank 1",       "address": {         "address1": "555 South North Lane",         "address2": "Floor 5",         "city": "Springfield",         "state": "VA",         "postalCode": 47060,         "country": "US"       }     }   },   "details": {     "paymentReference": "1234567890",     "purposeOfPayment": "Purchase of Goods",     "purposeOfPaymentFreeText": "Invoice 12345",     "regE": true   } }

 

Error Responses 

Status Code	Meaning
200 OK	Request successful
400 Bad Request	Invalid parameters. Read the error response body for error details
403 Forbidden	API key does not have permission to access this resource
500 Internal Server Error	Unexpected server error. Read the error response body for error details

 

Notes:

• The bankId (Routing Number) must be included in the request header.

• The originator and beneficiary details must be complete, including name, address, and contact details.

• The purpose of payment is required for compliance and can include structured codes or free-text explanations.

 

---

Update Payment

Modify an existing payment before it is approved or sent.

Endpoint:

PUT /payments/{paymentId}

Description:

This endpoint allows you to update the details of a payment before it has been approved or sent. Changes can be made to the originator, beneficiary, bank details, and payment purpose.

Request

Path Parameter

Parameter	Type	Description
paymentId	integer($int64)	(Required) The unique ID of the payment to update

 

Example Value

Example data is identical to POST /payments 

Response

Success Response (200 OK)

Example data is identical to create payment

Error Responses

Status Code	Meaning
200 OK	Request successful
400 Bad Request	Invalid parameters. Read the error response body for error details
403 Forbidden	API key does not have permission to access this resource
500 Internal Server Error	Unexpected server error. Read the error response body for error details

 

Notes:

• Payments can only be updated before approval or processing.

• The bankId (Routing Number) is required in the request header.

• If a payment has already been approved or sent, updates are not allowed.

• Only certain fields can be modified, such as:

  • Originator details

  • Beneficiary details

  • Bank account details

 

---

Approve Payment 

Endpoint

POST /payments/{paymentId}/approve

Description

This endpoint is used to approve a payment that is currently in a pending state. Approving a payment releases it for sending, pending additional validations.

Request Parameters

Parameter	Type	Required	Description
paymentId	Path	Yes	The unique identifier of the payment to be approved.

 

Request Example

No JSON request body is required for this API endpoint 

Response Example (Success - 200 OK)

No JSON data is returned on a successful approval (200 OK)

 

Error Responses

Status Code	Error Message	Description
400	Invalid request	The request is missing required fields or has invalid data.
403	Permission denied	The user does not have the necessary permissions to approve payments.
404	Payment not found	The specified paymentId does not exist.
500	Internal Server Error	A system error occurred while processing the request.

 

Notes:

• Approved payments cannot be cancelled automatically.

• Ensure that the paymentId provided corresponds to a valid pending payment.

 

---

Cancel Payment

Cancel a payment that is still in processing.

Endpoint:

DELETE /payments/{paymentId}

Description:

This endpoint allows you to cancel a payment before it has been fully processed. Payments that are already completed cannot be canceled.

 

Path Parameter

Parameter	Type	Description
paymentId	string	Unique identifier for the payment

 

Response

Success Response (200 OK)

No JSON data is returned on a successful approval (200 OK)

Error Responses

Status Code	Error Message	Description
400	"Invalid request parameters"	The payment ID provided is invalid
403	"Forbidden"	API key does not have permission to cancel this payment
500	"Internal Server Error"	Unexpected error on the server side

 

Notes:

• Only pending or processing payments can be canceled.
• Cancellations are irreversible once confirmed.
• Payment cancellations do not cancel underlying locked rate. Existing locked rate can be reused for a corrected payment. If payment will not be resent with corrected data, locked rate must be cancelled.

If a payment was already approved or completed, it cannot be canceled.