Skip to content

rail API Specification (1.1.2)

Welcome to the rail Developer Guide!

Download OpenAPI description
rail-spec.json
rail-spec.yaml
Languages
Servers
Mock server

https://docs.rail.io/_mock/api-docs/openapi/rail-spec/

Sandbox - Stable API Instance

https://sandbox.layer2financial.com/api/

Production - Stable API Instance

https://platform.layer2financial.com/api/

Applications

Applications represent the onboarding journey for your customers. They are used to collect KYC information and documents required to open accounts on the platform. Visit our guides for a detailed understanding on how to use these APIs.

Operations

Accounts

Accounts are used to hold funds on the platform. Once a customer is onboarded via the application process, you can create accounts for them in various currencies.

Operations

Counterparties

Counterparties represent external entities that you may wish to send or receive funds from. All counterparties are verified to ensure compliance with regulatory requirements prior to being available for use for withdrawals.

Operations

Customers

Customers can only be created via the application process. Once created, customers can have multiple accounts associated with them.

Operations

Deposits

Deposits are used to request instructions for funding platform managed accounts from external sources. A given account may have many deposits associated with it depending on the supported rails and configurations.

Operations

Documents

Document uploading and management functions.

Operations

Exchanges

Exchanges are used to convert funds from one currency to another. This is achieved by moving money between 2 platform accounts that are denominated in different currencies. We have eliminated the complexity of traditional currency trading.

Operations

Payments

Payments are used to orchestrate end to end payment flows from external parties or from within the platform.

Operations

Transactions

Transactions are created to record the movement of funds between accounts. The transactions endpoint allows the bulk retrieval of transaction data for reconciliation and reporting purposes.

Operations

Transfers

Transfer are used to move funds between two platform managed accounts that are denominated in the same currency.

Operations

Withdrawals

Move funds from a platform managed account to an external counterparty via supported rails.

Operations

Create Withdrawal

Request

Request a new withdrawal. On successful request, the withdrawal must be accepted before it is queued for execution. Withdrawals accepted before

Security
OAuth2Flow
Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

Bodyapplication/jsonrequired
withdrawal_railstringrequired

The rail to be used for the withdrawal. The destination counterparty must have the appropriate rail configuration.

Enum"ACH""FEDWIRE""SEPA_CT""SWIFT""CRYPTO""EFT"
Discriminator
descriptionstring

Description of the transaction

source_account_idstringrequired

Source account ID from which funds will be withdrawn.

purposestringrequired

Purpose of the withdrawal. (Note: The purpose "PERSONAL_ACCOUNT" is only valid with counterparties that have profile.relationship_to_customer set as "SELF".)

Enum"PERSONAL_ACCOUNT""FAMILY""INSURANCE""INVESTMENT""REAL_ESTATE""TUITION""MEDICAL""TRAVEL""TRADE_TRANSACTIONS""UTILITY"
amountnumberrequired

Amount to be withdrawn (uses the source account currency)

destination_counterparty_idstringrequired

Destination counterparty where funds will be sent. This counterparty must be configured with the required rail information.

memostring<= 10 characters

Memo to provide on the outbound ACH

curl -i -X POST \
  https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/withdrawals \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -d '{
    "withdrawal_rail": "ACH",
    "description": "string",
    "source_account_id": "string",
    "purpose": "PERSONAL_ACCOUNT",
    "amount": 0,
    "destination_counterparty_id": "string",
    "memo": "string"
  }'

Responses

Success

Bodyapplication/json
dataobject(WithdrawalBase)required
data.​idstringread-only

Unique Identifier for the withdrawal request

data.​statusstringread-only

Status of the withdrawal.

  • REQUESTED - Withdrawal request is created and has passed validation. It must be accepted at which point it will be executed.
  • ACCEPTED - Withdrawal request has been accepted and is waiting execution. At this point it cannot be cancelled.
  • EXPIRED - Occurs when a withdrawal request was not accepted within a reasonable time frame. The request cannot be replayed from this state.
  • CANCELLED - Withdrawal request was cancelled. Only available prior to acceptance. The request cannot be replayed from this state.
  • CANCELLING - Withdrawal request is being cancelled.
  • EXECUTED - Withdrawal request has been executed, it is completed with all ledger entries performed.
  • REJECTED - Withdrawal request was rejected and cannot be executed.
Enum"REQUESTED""REJECTED""EXPIRED""ACCEPTED""EXECUTED""CANCELLED""CANCELLING"
Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED"
  }
}

Cancel Withdrawal

Request

Cancel a withdrawal. This will submit a withdrawal cancellation request. Some withdrawals may not be cancellable, if the funds have already been processed and sent externally.

Security
OAuth2Flow
Path
idstringrequired

Withdrawal ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

curl -i -X POST \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/withdrawals/{withdrawal_id}/cancel' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/json
dataobject(WithdrawalCancel)required
data.​idstringread-only

Unique Identifier for the withdrawal cancellation

data.​statusstringread-only

Status of the withdrawal cancellation. This will always be CANCELLING.

Enum"REQUESTED""REJECTED""EXPIRED""ACCEPTED""EXECUTED""CANCELLED""CANCELLING"
Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED"
  }
}

Accept Withdrawal

Request

Accept a withdrawal. This will execute the withdrawal and may not be reversible

Security
OAuth2Flow
Path
idstringrequired

Withdrawal ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

x-signaturestring

Client signature to validate the provence of the API request. See signing section for more details.

x-timestampstring

Current timestamp, represented AS unix epoch seconds. Mandatory when x-signature is provided.

curl -i -X POST \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/withdrawals/{withdrawal_id}/accept' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -H 'x-signature: string' \
  -H 'x-timestamp: string'

Responses

Success

Bodyapplication/json
dataobject(WithdrawalBase)required
data.​idstringread-only

Unique Identifier for the withdrawal request

data.​statusstringread-only

Status of the withdrawal.

  • REQUESTED - Withdrawal request is created and has passed validation. It must be accepted at which point it will be executed.
  • ACCEPTED - Withdrawal request has been accepted and is waiting execution. At this point it cannot be cancelled.
  • EXPIRED - Occurs when a withdrawal request was not accepted within a reasonable time frame. The request cannot be replayed from this state.
  • CANCELLED - Withdrawal request was cancelled. Only available prior to acceptance. The request cannot be replayed from this state.
  • CANCELLING - Withdrawal request is being cancelled.
  • EXECUTED - Withdrawal request has been executed, it is completed with all ledger entries performed.
  • REJECTED - Withdrawal request was rejected and cannot be executed.
Enum"REQUESTED""REJECTED""EXPIRED""ACCEPTED""EXECUTED""CANCELLED""CANCELLING"
Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED"
  }
}

Retrieve Withdrawal

Request

Retrieves details of a previously requested withdrawal

Security
OAuth2Flow
Path
idstringrequired

Withdrawal ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

curl -i -X GET \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/withdrawals/{withdrawal_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/json
One of:
dataobject(WithdrawalCrypto)required
data.​idstringread-only

Unique Identifier for the withdrawal request

data.​statusstringread-only

Status of the withdrawal.

  • REQUESTED - Withdrawal request is created and has passed validation. It must be accepted at which point it will be executed.
  • ACCEPTED - Withdrawal request has been accepted and is waiting execution. At this point it cannot be cancelled.
  • EXPIRED - Occurs when a withdrawal request was not accepted within a reasonable time frame. The request cannot be replayed from this state.
  • CANCELLED - Withdrawal request was cancelled. Only available prior to acceptance. The request cannot be replayed from this state.
  • CANCELLING - Withdrawal request is being cancelled.
  • EXECUTED - Withdrawal request has been executed, it is completed with all ledger entries performed.
  • REJECTED - Withdrawal request was rejected and cannot be executed.
Enum"REQUESTED""REJECTED""EXPIRED""ACCEPTED""EXECUTED""CANCELLED""CANCELLING"
data.​created_timestampstring(date-time)read-onlyrequired

Time when the withdrawal request was generated

data.​withdrawal_railstringrequired

The rail to be used for the withdrawal. The destination counterparty must have the appropriate rail configuration.

Enum"ACH""FEDWIRE""SEPA_CT""SWIFT""CRYPTO""EFT"
data.​descriptionstring

Description of the transaction

data.​source_account_idstringrequired

Source account ID from which funds will be withdrawn.

data.​purposestringrequired

Purpose of the withdrawal. (Note: The purpose "PERSONAL_ACCOUNT" is only valid with counterparties that have profile.relationship_to_customer set as "SELF".)

Enum"PERSONAL_ACCOUNT""FAMILY""INSURANCE""INVESTMENT""REAL_ESTATE""TUITION""MEDICAL""TRAVEL""TRADE_TRANSACTIONS""UTILITY"
data.​amountnumberrequired

Amount to be withdrawn (uses the source account currency)

data.​destination_counterparty_idstringrequired

Destination counterparty where funds will be sent. This counterparty must be configured with the required rail information.

Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED",
    "created_timestamp": "2019-08-24T14:15:22Z",
    "withdrawal_rail": "ACH",
    "description": "string",
    "source_account_id": "string",
    "purpose": "PERSONAL_ACCOUNT",
    "amount": 0,
    "destination_counterparty_id": "string"
  }
}

Retrieve Withdrawal Status

Request

Retrieves status of a previously requested withdrawal

Security
OAuth2Flow
Path
idstringrequired

Withdrawal ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

curl -i -X GET \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/withdrawals/{withdrawal_id}/status' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/json
dataobject(WithdrawalState)required
data.​idstringread-only

Unique Identifier for the withdrawal request

data.​statusstringread-only

Status of the withdrawal.

  • REQUESTED - Withdrawal request is created and has passed validation. It must be accepted at which point it will be executed.
  • ACCEPTED - Withdrawal request has been accepted and is waiting execution. At this point it cannot be cancelled.
  • EXPIRED - Occurs when a withdrawal request was not accepted within a reasonable time frame. The request cannot be replayed from this state.
  • CANCELLED - Withdrawal request was cancelled. Only available prior to acceptance. The request cannot be replayed from this state.
  • CANCELLING - Withdrawal request is being cancelled.
  • EXECUTED - Withdrawal request has been executed, it is completed with all ledger entries performed.
  • REJECTED - Withdrawal request was rejected and cannot be executed.
Enum"REQUESTED""REJECTED""EXPIRED""ACCEPTED""EXECUTED""CANCELLED""CANCELLING"
data.​document_errorsArray of objects(WithdrawalDocumentError)read-only

List of document errors associated with the withdrawal

Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED",
    "document_errors": [ … ]
  }
}

Retrieve Withdrawal Receipt

Request

Retrieves a receipt for a previously completed withdrawal.

Security
OAuth2Flow
Path
idstringrequired

Withdrawal ID

Headers
Authorizationstring

Bearer token for authentication

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

curl -i -X GET \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/withdrawals/{withdrawal_id}/receipt' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/octet-stream
Response
No content

Settlements

Settlement services for funds confirmation and reconciliation. Settlements are a deprecated concept and will be removed in future versions of the API. Please use Payments for all new integrations.

Operations

Subscriptions (Webhooks)

Manage your callback (webhook) subscriptions. Subscriptions allow you to receive real-time notifications of events that occur within your platform instance. Visit the guides for a full breakdown of all available events.

Operations
© 2026 Rail. All Rights Reserved.