Payments Guide
Version Differences
This endpoint is available in API versions 2 and 3. Note the following differences:
Area | V2 | V3 |
|---|---|---|
x-akoya-interaction-type header | Optional | Required |
x-akoya-last-access header | Not Supported | Required |
x-akoya-intent-type header | Not Supported | Required |
Overview
Payments includes account payment information such as bankId, identifier, type, and identifierType.
Some data providers support tokenized account numbers. If the paymentNetworks response indicates that the identifierType is TOKENIZED_ACCOUNT_NUMBER, then the account number is tokenized. Refer to Account Number Tokenization FAQs.
Payments returns results in JSON in FDX format.
Use Cases
Account Opening: Enable account opening and funding without micro-deposits (in conjunction with Balances and Customers)
Account Verification: Verify the account number and routing number retrieved from the consumer.
Payment Enablement: Authorize account-to-account or person-to-person payments with instant account authentication.
Security
The Payments API requires authentication using a bearer token (id_token assigned to the permissioned user). You should include the id_token in the Authorization header of each request. The actual token lifetime varies by provider, but assume a lifetime of 15 minutes and code your application to automatically refresh the token if it has expired.
Base URL
Like all Akoya APIs, Payments operates in both sandbox and prod:
Sandbox:
https://sandbox-products.ddp.akoya.com
Production:
https://products.ddp.akoya.com
Endpoints
Account Information
GET /payments/{version}/{providerId}/{accountId}/payment-networks
Payments supports use cases such as payment enablement or account opening. The response includes identifiers necessary to make ACH and RTP payments. Identifiers include account number, routing number, identifier type (actual or tokenized account number), and payment network type such as ACH or RTP.
Path Params
Param | Description |
|---|---|
{version} | Major API version (e.g. v3) |
{providerId} | ID for the financial institution providing the data |
{accountId} | The consumer’s unique account identifier (not the account number) |
Query Params
Param | Type | Required | Description |
|---|---|---|---|
(None) | --- | --- | --- |
Headers
Header | Type | Required | Description |
|---|---|---|---|
Authorization | String | Yes | The ID Token for the permissioned user |
x-akoya-interaction-type | String (Enum) | v2: No v3: Yes | Indicates whether a consumer action prompted the request (USER) or the request is part of a batch process (BATCH) |
x-akoya-last-access | String (Date-Time) | v2: N/A v3: Yes | The date and time stamp for the last active use by the user. |
x-akoya-intent-type | String (Enum) | v2: N/A v3: Yes | Indicates whether a transaction involves a payment. Acceptable values are payments or nonpayments. |
Example Response
JSON
Supported Data Elements
Name | Type | Description |
|---|---|---|
bankId | String | Bank identifier used by the payment network i.e. Routing Number |
identifier | String | The number used to identify the account within the payment network. If identifierType is ACCOUNT_NUMBER, this is the account number. |
identifierType | String | Type of identifier |
type | String | Type of payment network |
transferIn | Boolean | Can transfer funds to the account using this information |
transferOut | Boolean | Can transfer funds from the account using this information |
Error Responses
See our error documentation.