--- updatedAt: 2026-09-29T10:41:30.000Z agentTools: projectIndex: https://docs.sumsub.com/llms.txt --- # Add payment method # Overview Use this endpoint to add and store an applicant payment method. This helps link applicants to their payment methods (e.g., bank accounts, crypto wallets), which is important for [processing inbound Travel Rule messages](https://docs.sumsub.com/sumsub/docs/receive-inbound-travel-rule-message). When submitting the crypto wallet data (`data.type == cryptoWallet`), you can send: * Only `accountIdentifier`, if you are ready to share the wallet addresses with Sumsub. * Only `accountIdentifierHash`, if you do not want to share direct wallet addresses for security reasons. Generate a SHA-256 hash of a wallet address (`new Sha256Hash(walletAddress).toBase64()`). * Both `accountIdentifierHash` and `accountIdentifier`, so you can check if your hashing function is the same as in Sumsub. In case the functions differ, the response returns an error. ### Note This endpoint is only relevant for existing applicants. ## Required permissions To use this method, your [app token](https://docs.sumsub.com/sumsub/docs/app-tokens) must have the **Change applicant's personal data** [permission](https://docs.sumsub.com/sumsub/docs/user-roles#permissions). ## Request examples Below, you can see the request examples for each available payment method type. ```curl bankCard curl -X POST 'https://api.sumsub.com/resources/applicants/6756c06e40c2f83feed00000/payments' \ -H 'content-type: application/json' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' \ -d '{ "externalId": "id_from_your_system", "data": { "type": "bankCard", "fullName": "John Doe", "accountIdentifier": "12345678*4321", "validUntil": "2030-12-01" } }' ``` ```curl bankAccount curl -X POST 'https://api.sumsub.com/resources/applicants/6756c06e40c2f83feed00000/payments' \ -H 'content-type: application/json' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' \ -d '{ "externalId": "id_from_your_system", "data": { "type": "bankAccount", "fullName": "John Doe", "accountIdentifier": "DE75512108001245126199" }, "institutionInfo": { "name": "Deutsche Bank", "code": "DEUTDEFFXXX", "address": { "country": "DEU" }, "issuer": { "type": "license" } } }' ``` ```curl eWallet curl -X POST 'https://api.sumsub.com/resources/applicants/6756c06e40c2f83feed00000/payments' \ -H 'content-type: application/json' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' \ -d '{ "externalId": "id_from_your_system", "data": { "type": "eWallet", "subType": "PayPal", "accountIdentifier": "A0AAAAA00AAAA" } }' ``` ```curl cryptoWallet curl -X POST 'https://api.sumsub.com/resources/applicants/6756c06e40c2f83feed00000/payments' \ -H 'content-type: application/json' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' \ -d '{ "externalId": "id_from_your_system", "data": { "type": "cryptoWallet", "cryptoChain": "XRP", "currencyCode": "USDT", "accountIdentifier": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh", "memo": "12345678" }, "institutionInfo": { "issuer": { "type": "license" } } }' ``` ```curl other curl -X POST 'https://api.sumsub.com/resources/applicants/6756c06e40c2f83feed00000/payments' \ -H 'content-type: application/json' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' \ -d '{ "externalId": "id_from_your_system", "data": { "type": "other", "subType": "your_domain_specific_type", "accountIdentifier": "ABC123" } }' ``` # Response explained The response is a JSON file that represents structured information on the payment method. | Field | Type | Description | | :---------------- | :------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- | | `id` | String | Identifier of the payment method in the Sumsub system. | | `externalId` | String | Identifier of the payment method on your side. | | `createdAt` | Date | Date and time when the payment method was submitted to the Sumsub system. Format `YYYY-MM-DD HH-MM-SS`, e.g., `2025-07-17 10:37:54`. | | `review` | [Object](#review-attributes) | Includes the status and other details of the payment method. | | `data` | [Object](#data-attributes) | Payment method data. | | `institutionInfo` | [Object](#institutionInfo-attributes) | Includes details about the financial institution used by a participant to execute the transaction. | ## `review` attributes | Field | Type | Description | | :------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reviewStatus` | String | Indicates the payment method review status. Possible statuses:
  • init — initiated.
  • pending — pending to be processed.
  • queued — in progress.
  • awaitingUser — user action is required.
  • onHold — assistance from a compliance expert is required.
  • prechecked — initial quick check is done.
  • completed — the check is completed, and the review answer is given whether the payment method is approved or rejected.
| | `createDate` | Date | Date and time (UTC) when the check was launched. | ## `data` attributes
Field Type Description
`type` String Type of the payment method. Can be one of the following: `bankCard`, `bankAccount`, `eWallet`, `cryptoWallet`, `other`.
`subType` String Subtype of the payment method (could be a domain specific type or a name, e.g., PayPal).
`accountIdentifier` String Plain (non-hashed) unique identifier of the account associated with this payment method. ⚠️ Returned if submitted in the request. Case-sensitive.
`accountIdentifierHash` String Hashed version of the account identifier. Hash function is sha256 for `cryptoWallet` type.
`fullName` String Full name of the account holder. Applicable to the `bankAccount` type.
`validUntill` Date Date field for the `bankCard` type indicating the date when the bank card is expired (format `yyyy-MM-dd`).
`currencyCode` String Code of the currency the wallet holds (`USD`, `GBP`, `BTC`, etc.). Applicable to the `cryptoWallet` type.
`cryptoChain` String Crypto chain name. Specifies the network name to which the token at `currencyCode` belongs. Empty for native tokens (for `BTC`, `ETH`, and so on). For more information, see [Working with Crypto Assets](https://docs.sumsub.com/sumsub/reference/working-with-crypto-assets). Applicable to the `cryptoWallet` type.
`memo` String Optional field for the `cryptoWallet` type in blockchain transactions to attach metadata or messages for identification, routing, or compliance purposes.
## `institutionInfo` attributes | Field | Type | Description | | :-------- | :----------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | | `code` | String | Institution code (e.g. BIC). | | `name` | String | Institution name (e.g., Wells Fargo). | | `address` | [Object](https://docs.sumsub.com/sumsub/reference/get-transaction#address-attributes) | Institution address. | | `issuer` | [Object](#issuer-attributes) | Describes who issued the payment method within the scope of the current license key. It can be either you or one of your applicants. | ## `issuer` attributes | Field | Type | Description | | :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | String |

Specifies the issuer of the payment method:

  • license — you as a license key owner.
  • applicant — the applicant (individual or company) under the current license.
| | `applicantId` | String | Identifier of the applicant (in the Sumsub system) who issued the payment method. Applicable when `issuer.type` is set to `applicant`. Can refer to either a KYB (company) or KYC (individual) applicant. |
## Response examples If the request is successfully sent and processed, you will get a response like one of those below. ```json bankCard { "id": "6878d282f69224a473d00000", "externalId": "6456526565", "createdAt": "2025-07-17 10:37:54", "review": { "reviewStatus": "init", "createDate": 1752748674638 }, "data": { "type": "bankCard", "fullName": "John Doe", "accountIdentifier": "12345678*4321", "validUntil": "2030-12-01" } } ``` ```json bankAccount { "id": "6878d282f69224a473d00000", "externalId": "6456526565", "createdAt": "2025-07-17 10:37:54", "review": { "reviewStatus": "init", "createDate": 1752748674638 }, "data": { "type": "bankAccount", "fullName": "John Doe", "accountIdentifier": "DE75512108001245126199" }, "institutionInfo": { "name": "Deutsche Bank", "code": "DEUTDEFFXXX", "address": { "country": "DEU" }, "issuer": { "type": "license" } } } ``` ```json eWallet { "id": "6878d282f69224a473d00000", "externalId": "6456526565", "createdAt": "2025-07-17 10:37:54", "review": { "reviewStatus": "init", "createDate": 1752748674638 }, "data": { "type": "eWallet", "subType": "PayPal", "accountIdentifier": "A0AAAAA00AAAA" } } ``` ```json cryptoWallet { "id": "6878d282f69224a473d00000", "externalId": "6456526565", "createdAt": "2025-07-17 10:37:54", "review": { "reviewStatus": "init", "createDate": 1752748674638 }, "data": { "type": "cryptoWallet", "cryptoChain": "XRP", "currencyCode": "USDT", "accountIdentifier": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh", "memo": "12345678" }, "institutionInfo": { "issuer": { "type": "license" } } } ``` ```json other { "id": "6878d282f69224a473d00000", "externalId": "6456526565", "createdAt": "2025-07-17 10:37:54", "review": { "reviewStatus": "init", "createDate": 1752748674638 }, "data": { "type": "other", "subType": "your_domain_specific_type", "accountIdentifier": "ABC123" } } ``` If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example: ```json { "description": "data.accountIdentifier must not be null", "code": 400, "correlationId": "cc4616424ce1d7bf5a6cad414e8e76d6" } ``` # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "sumsub-api", "version": "1.0" }, "servers": [ { "url": "https://api.sumsub.com" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "name": "X-App-Token", "in": "header", "x-default": "" } } }, "security": [ { "sec0": [] } ], "paths": { "/resources/api/applicants/{applicantId}/payments": { "post": { "summary": "Add payment method", "description": "", "operationId": "add-payment-method", "parameters": [ { "name": "applicantId", "in": "path", "description": "Unique identifier of the applicant in the Sumsub system.

This identifier is a random combination of 24 digits and lowercase Latin characters. It is automatically generated when the applicant is created on the Sumsub side, and can be found in the [Dashboard](https://cockpit.sumsub.com/checkus/#/applicants/individual?limit=10&page=0).

If the `applicantId` is unknown to you, use the [Get applicant data (externalUserId)](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) method to fetch it.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "externalId", "data" ], "properties": { "externalId": { "type": "string", "description": "Identifier of the payment method on your side." }, "data": { "type": "object", "description": "Payment method data.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Payment method type.", "enum": [ "bankCard", "bankAccount", "eWallet", "cryptoWallet", "other" ] }, "subType": { "type": "string", "description": "Subtype of the payment method (domain specific type).

ⓘ Applicable to the `eWallet` and `other` types." }, "accountIdentifier": { "type": "string", "description": "Plain (non-hashed) unique identifier of the account associated with this payment method. This field is optional if `accountIdentifierHash` is provided.

⚠️ Either `accountIdentifier` or `accountIdentifierHash` must be included." }, "accountIdentifierHash": { "type": "string", "description": "Hashed version of the account identifier. Use this field if you prefer not to expose the raw `accountIdentifier`. This field is optional when `accountIdentifier` is provided.

⚠️ Either `accountIdentifier` or `accountIdentifierHash` must be included. Hash function is sha256 for `cryptoWallet` type." }, "fullName": { "type": "string", "description": "Full name of the payment method holder. E.g., John Doe.

ⓘ Applicable to the `bankCard` and `bankAccount` types." }, "validUntil": { "type": "string", "description": "Indicates the date when the bank card is expired (format yyyy-MM-dd).

ⓘ Applicable to the `bankCard` type only.", "format": "date" }, "cryptoChain": { "type": "string", "description": "Crypto chain name. Mandatory for crypto tokens only. Specifies the network name to which the token at currencyCode belongs. Empty for native tokens (for `BTC`, `ETH`, and so on). For more information, see [Working with Crypto Assets](https://docs.sumsub.com/sumsub/reference/working-with-crypto-assets).\n\n⚠️ Applicable to the `cryptoWallet` type only." }, "currencyCode": { "type": "string", "description": "Code of the currency the wallet holds (`USD`, `GBP`, `BTC`, and so on). \n\n⚠️ Applicable to the `cryptoWallet` type only." }, "memo": { "type": "string", "description": "Optional field to attach metadata or messages for identification, routing, or compliance purposes. \n\n⚠️ Applicable to the `cryptoWallet` type only." } } }, "institutionInfo": { "type": "object", "description": "Financial institution information.", "properties": { "name": { "type": "string", "description": "Institution name (e.g., Wells Fargo)." }, "code": { "type": "string", "description": "Institution code (e.g. BIC)." }, "address": { "type": "object", "description": "Institution address.", "properties": { "country": { "type": "string", "description": "Alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on)." }, "postCode": { "type": "string", "description": "Address postal code." }, "town": { "type": "string", "description": "The city, town, or another settlement." }, "street": { "type": "string", "description": "Street name." }, "subStreet": { "type": "string", "description": "Additional information related to the street. This could be a house number or any other details." }, "state": { "type": "string", "description": "The state, region, district, county or another territorial entity inside a country (if applicable)." }, "buildingName": { "type": "string", "description": "Building name (if applicable)." }, "flatNumber": { "type": "string", "description": "Flat or apartment number." }, "buildingNumber": { "type": "string", "description": "Building number." }, "formattedAddress": { "type": "string", "description": "Address in a human readable format. For example, `Design Offices, Philipsbornstraße 2, 30165 Hannover, Germany`." } } }, "issuer": { "type": "object", "description": "Describes who issued the payment method within the scope of the current license key. It can be either you or one of your applicants.", "properties": { "type": { "type": "string", "description": "

Specify the issuer of the payment method:

  • license — you as a license key owner.
  • applicant — the applicant (individual or company) under the current license.
", "enum": [ "license", "applicant" ] }, "applicantId": { "type": "string", "description": "Identifier of the applicant (in the Sumsub system) who issued the payment method. Required when `issuer.type` is set to `applicant`. Can refer to either a KYB (company) or KYC (individual) applicant." } } } } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```