To manage certain aspects of the 3D Secure (3DS) authentication, you will need to integrate with the following APIs.
Wise Platform API
The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.
New to wise?
We strongly recommend first reading our Getting Started Guide to help you set up credentials and make your first call.
Before you begin
To use this API reference effectively, you should have:
- Received Valid API credentials from Wise (Client ID and Client Secret)
- Understand OAuth 2.0 authentication
- Be familiar with RESTful API concepts
Core API resources
| Resource | Purpose |
|---|---|
| Quote | Exchange rate and fee calculations |
| Recipient | Beneficiary account management |
| Transfer | Payment creation and execution |
| Balance | Multi-currency account operations |
| Profile | Account ownership details |
| Rate | Current and historical exchange rates |
Not sure which workflow to build?
Start with our Integration Guides for step-by-step implementation examples.
Languages
Servers
Production Environment
https://api.wise.com/
Sandbox Environment
https://api.wise-sandbox.com/
Additional Customer Verification
In certain situations, additional evidence is required to verify customers and ensure we’re compliant with the KYC regulations.
Additional Verification APIs support a list of evidences that can be found in the Supported Evidences guide.
If you use the Customer Account with Partner KYC model and your customers are primarily based in the EU, refer to this Onboarding EU customers guide for instructions on how to use these APIs.
If you use the Customer Account with Partner KYC model and you are onboarding high risk business customers based primarily based in the US, refer to this Onboarding High Risk US Businesses guide for instructions on how to use these APIs.
Operations
Balance
Create and manage balance accounts within a multi-currency account.
Each profile can hold multiple balance accounts in different currencies. A STANDARD balance is limited to one per currency, while SAVINGS balances (Jars) allow multiple in the same currency. Creating the first balance for a profile automatically creates the multi-currency account.
Balances include an investmentState field. Only balances with NOT_INVESTED can be operated on via the API. Invested balances should be shown but not actionable.
For a complete guide on multi-currency accounts, see Multi-Currency Accounts.
SchemasOperations
Bank Account Details
Bank account details allow users to receive money into their Wise Multi-Currency Account. Each currency balance can have local bank details (for domestic payments) and international bank details (for SWIFT payments) where available.
Bank account details can be retrieved for existing balances, or new details can be ordered for currencies where they're available but not yet issued.
SchemasOperations
Batch Group
A batch group is a named collection of up to 1000 transfers that can be managed as a single unit. Batch groups are primarily used for funding multiple transfers with a single payment.
Workflow:
- Create a batch group with a source currency
- Add transfers to the group (up to 1000)
- Complete the batch group to close it for modifications
- Fund the batch group from a balance or via direct debit
Individual transfers in the group follow standard transfer lifecycle and can be tracked separately.
SchemasOperations
Batch Group
Batch version, used for concurrency control. This number is updated whenever there is a change to the batch group state (its status, the identity of the transfers in the batch, etc).
Some API operations require this version in requests, and operations may be rejected when the requested version does not match the server's version.
The version is a signed integer and is not ordered with respect to any previous version.
Example: 123
Source currency code (ISO 4217 Alphabetic Code). This currency is expected to be used for funding the batch group.
Example: "GBP"
Current batch group status:
NEW— New batch group with zero or more transfers. Able to have more transfers added to it. Transfers in aNEWgroup cannot yet be funded and paid out.COMPLETED— The batch group has had all desired transfers added and is now closed to further changes. Transfers in the group can now be funded and paid out. Note:COMPLETEDdoes not imply payouts have been successfully completed.MARKED_FOR_CANCELLATION— Cancellation of the transfers in the batch group was requested.PROCESSING_CANCEL— Transfers in the group are being cancelled.CANCELLED— Transfers in the group have been cancelled.
Enum"NEW""COMPLETED""MARKED_FOR_CANCELLATION""PROCESSING_CANCEL""CANCELLED"
Example: "COMPLETED"
The IDs of all transfers successfully added to the group.
Example: [234,456]
List of pay-in details describing how the batch group can be funded. Provided only when the batch group is in the COMPLETED state.
Currently supported types: bank_transfer.
The reference that should be used when funding the transfers in the batch group. This reference should be treated as an opaque value and there should be no attempt to decode or decompose it.
Example: "B5323"
The total pay-in amount for all transactions in the batch when paying in with this reference and method.
Example: 12504.54
Name of the bank branch. Provided only when the currency route requires it (such as JPY).
Example: null
Bank account type. Provided only when the currency route requires it.
Example: null
Bank identifier or routing number, depending on pay-in type and currency.
Example: "8301"
Address for the receiving bank. Provided only when the currency route requires it.
Wise's address. Provided only when the currency route requires it.
ISO 13616 International Bank Account Number (when available).
Example: null
Basic Bank Account Number (BBAN). Provided only when the currency route requires it (such as NOK).
Example: "83019910728"
Financial Institution number (3 digits). Provided only when the currency route requires it (such as CAD).
Example: null
Branch Transit Number (5 digits). Provided only when the currency route requires it (such as CAD).
Example: null
Beneficiary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).
Example: null
Intermediary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).
Example: null
Faster Payment System identifier. Provided only when the currency route requires it (such as HKD).
Example: null
{ "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88", "version": 123, "name": "My batch group", "sourceCurrency": "GBP", "status": "COMPLETED", "transferIds": [ 234, 456 ], "payInDetails": [ { "type": "bank_transfer", "reference": "B5323", "amount": 12504.54, "currency": "NOK", "name": "TransferWise Ltd", "branchName": null, "accountNumber": "9910728", "accountType": null, "bankCode": "8301", "bankAddress": { … }, "transferWiseAddress": { … }, "iban": null, "bban": "83019910728", "institutionNumber": null, "transitNumber": null, "beneficiaryBankBIC": null, "intermediaryBankBIC": null, "fpsIdentifier": null, "clearingNumber": null } ] }
Bodyapplication/jsonrequired
Source currency code (ISO 4217 Alphabetic Code). This currency is expected to be used for funding the batch group.
Example: "GBP"
- Production Environmenthttps://api.wise.com/v3/profiles/{profileId}/batch-groups
- Sandbox Environmenthttps://api.wise-sandbox.com/v3/profiles/{profileId}/batch-groups
curl -i -X POST \
https://api.wise.com/v3/profiles/12345678/batch-groups \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"sourceCurrency": "GBP",
"name": "My batch group"
}'Batch group created successfully.
Note that payInDetails is empty for newly created batch groups.
Batch version, used for concurrency control. This number is updated whenever there is a change to the batch group state (its status, the identity of the transfers in the batch, etc).
Some API operations require this version in requests, and operations may be rejected when the requested version does not match the server's version.
The version is a signed integer and is not ordered with respect to any previous version.
Example: 123
Source currency code (ISO 4217 Alphabetic Code). This currency is expected to be used for funding the batch group.
Example: "GBP"
Current batch group status:
NEW— New batch group with zero or more transfers. Able to have more transfers added to it. Transfers in aNEWgroup cannot yet be funded and paid out.COMPLETED— The batch group has had all desired transfers added and is now closed to further changes. Transfers in the group can now be funded and paid out. Note:COMPLETEDdoes not imply payouts have been successfully completed.MARKED_FOR_CANCELLATION— Cancellation of the transfers in the batch group was requested.PROCESSING_CANCEL— Transfers in the group are being cancelled.CANCELLED— Transfers in the group have been cancelled.
Enum"NEW""COMPLETED""MARKED_FOR_CANCELLATION""PROCESSING_CANCEL""CANCELLED"
Example: "COMPLETED"
The IDs of all transfers successfully added to the group.
Example: [234,456]
List of pay-in details describing how the batch group can be funded. Provided only when the batch group is in the COMPLETED state.
Currently supported types: bank_transfer.
The reference that should be used when funding the transfers in the batch group. This reference should be treated as an opaque value and there should be no attempt to decode or decompose it.
Example: "B5323"
The total pay-in amount for all transactions in the batch when paying in with this reference and method.
Example: 12504.54
Name of the bank branch. Provided only when the currency route requires it (such as JPY).
Example: null
Bank account type. Provided only when the currency route requires it.
Example: null
Bank identifier or routing number, depending on pay-in type and currency.
Example: "8301"
Address for the receiving bank. Provided only when the currency route requires it.
Wise's address. Provided only when the currency route requires it.
ISO 13616 International Bank Account Number (when available).
Example: null
Basic Bank Account Number (BBAN). Provided only when the currency route requires it (such as NOK).
Example: "83019910728"
Financial Institution number (3 digits). Provided only when the currency route requires it (such as CAD).
Example: null
Branch Transit Number (5 digits). Provided only when the currency route requires it (such as CAD).
Example: null
Beneficiary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).
Example: null
Intermediary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).
Example: null
Faster Payment System identifier. Provided only when the currency route requires it (such as HKD).
Example: null
Response
application/json
{ "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88", "version": 0, "name": "My batch group", "sourceCurrency": "GBP", "status": "NEW", "transferIds": [], "payInDetails": [] }
- Production Environmenthttps://api.wise.com/v3/profiles/{profileId}/batch-groups/{batchGroupId}
- Sandbox Environmenthttps://api.wise-sandbox.com/v3/profiles/{profileId}/batch-groups/{batchGroupId}
curl -i -X GET \
https://api.wise.com/v3/profiles/12345678/batch-groups/54a6bc09-cef9-49a8-9041-f1f0c654cd88 \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Batch group retrieved successfully.
Batch version, used for concurrency control. This number is updated whenever there is a change to the batch group state (its status, the identity of the transfers in the batch, etc).
Some API operations require this version in requests, and operations may be rejected when the requested version does not match the server's version.
The version is a signed integer and is not ordered with respect to any previous version.
Example: 123
Source currency code (ISO 4217 Alphabetic Code). This currency is expected to be used for funding the batch group.
Example: "GBP"
Current batch group status:
NEW— New batch group with zero or more transfers. Able to have more transfers added to it. Transfers in aNEWgroup cannot yet be funded and paid out.COMPLETED— The batch group has had all desired transfers added and is now closed to further changes. Transfers in the group can now be funded and paid out. Note:COMPLETEDdoes not imply payouts have been successfully completed.MARKED_FOR_CANCELLATION— Cancellation of the transfers in the batch group was requested.PROCESSING_CANCEL— Transfers in the group are being cancelled.CANCELLED— Transfers in the group have been cancelled.
Enum"NEW""COMPLETED""MARKED_FOR_CANCELLATION""PROCESSING_CANCEL""CANCELLED"
Example: "COMPLETED"
The IDs of all transfers successfully added to the group.
Example: [234,456]
List of pay-in details describing how the batch group can be funded. Provided only when the batch group is in the COMPLETED state.
Currently supported types: bank_transfer.
The reference that should be used when funding the transfers in the batch group. This reference should be treated as an opaque value and there should be no attempt to decode or decompose it.
Example: "B5323"
The total pay-in amount for all transactions in the batch when paying in with this reference and method.
Example: 12504.54
Name of the bank branch. Provided only when the currency route requires it (such as JPY).
Example: null
Bank account type. Provided only when the currency route requires it.
Example: null
Bank identifier or routing number, depending on pay-in type and currency.
Example: "8301"
Address for the receiving bank. Provided only when the currency route requires it.
Wise's address. Provided only when the currency route requires it.
ISO 13616 International Bank Account Number (when available).
Example: null
Basic Bank Account Number (BBAN). Provided only when the currency route requires it (such as NOK).
Example: "83019910728"
Financial Institution number (3 digits). Provided only when the currency route requires it (such as CAD).
Example: null
Branch Transit Number (5 digits). Provided only when the currency route requires it (such as CAD).
Example: null
Beneficiary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).
Example: null
Intermediary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).
Example: null
Faster Payment System identifier. Provided only when the currency route requires it (such as HKD).
Example: null
Response
application/json
{ "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88", "version": 123, "name": "My batch group", "sourceCurrency": "GBP", "status": "COMPLETED", "transferIds": [ 234, 456 ], "payInDetails": [ { "type": "bank_transfer", "reference": "B5323", "amount": 12504.54, "currency": "NOK", "name": "TransferWise Ltd", "branchName": null, "accountNumber": "9910728", "accountType": null, "bankCode": "8301", "bankAddress": { … }, "transferWiseAddress": { … }, "iban": null, "bban": "83019910728", "institutionNumber": null, "transitNumber": null, "beneficiaryBankBIC": null, "intermediaryBankBIC": null, "fpsIdentifier": null, "clearingNumber": null } ] }
Request
Update a batch group's status to complete or cancel it.
Complete a batch group: Set status to COMPLETED to close the group for modifications and allow funding to proceed. Once completed, payInDetails will be populated with funding instructions.
Cancel a batch group: Set status to CANCELLED to cancel all transfers in the batch. Only batches that are not funded can be cancelled. Cancellation is final and cannot be undone.
The version parameter is required for concurrency control. The operation will be rejected if the provided version does not match the server's current version.
Security
UserToken or PersonalToken
Status to update to:
COMPLETED— Close the group and allow fundingCANCELLED— Cancel the group and all transfers
Enum"COMPLETED""CANCELLED"
Example: "COMPLETED"
- Production Environmenthttps://api.wise.com/v3/profiles/{profileId}/batch-groups/{batchGroupId}
- Sandbox Environmenthttps://api.wise-sandbox.com/v3/profiles/{profileId}/batch-groups/{batchGroupId}
curl -i -X PATCH \
https://api.wise.com/v3/profiles/12345678/batch-groups/54a6bc09-cef9-49a8-9041-f1f0c654cd88 \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"status": "COMPLETED",
"version": 1234
}'Batch group updated successfully.
Batch version, used for concurrency control. This number is updated whenever there is a change to the batch group state (its status, the identity of the transfers in the batch, etc).
Some API operations require this version in requests, and operations may be rejected when the requested version does not match the server's version.
The version is a signed integer and is not ordered with respect to any previous version.
Example: 123
Source currency code (ISO 4217 Alphabetic Code). This currency is expected to be used for funding the batch group.
Example: "GBP"
Current batch group status:
NEW— New batch group with zero or more transfers. Able to have more transfers added to it. Transfers in aNEWgroup cannot yet be funded and paid out.COMPLETED— The batch group has had all desired transfers added and is now closed to further changes. Transfers in the group can now be funded and paid out. Note:COMPLETEDdoes not imply payouts have been successfully completed.MARKED_FOR_CANCELLATION— Cancellation of the transfers in the batch group was requested.PROCESSING_CANCEL— Transfers in the group are being cancelled.CANCELLED— Transfers in the group have been cancelled.
Enum"NEW""COMPLETED""MARKED_FOR_CANCELLATION""PROCESSING_CANCEL""CANCELLED"
Example: "COMPLETED"
The IDs of all transfers successfully added to the group.
Example: [234,456]
List of pay-in details describing how the batch group can be funded. Provided only when the batch group is in the COMPLETED state.
Currently supported types: bank_transfer.
The reference that should be used when funding the transfers in the batch group. This reference should be treated as an opaque value and there should be no attempt to decode or decompose it.
Example: "B5323"
The total pay-in amount for all transactions in the batch when paying in with this reference and method.
Example: 12504.54
Name of the bank branch. Provided only when the currency route requires it (such as JPY).
Example: null
Bank account type. Provided only when the currency route requires it.
Example: null
Bank identifier or routing number, depending on pay-in type and currency.
Example: "8301"
Address for the receiving bank. Provided only when the currency route requires it.
Wise's address. Provided only when the currency route requires it.
ISO 13616 International Bank Account Number (when available).
Example: null
Basic Bank Account Number (BBAN). Provided only when the currency route requires it (such as NOK).
Example: "83019910728"
Financial Institution number (3 digits). Provided only when the currency route requires it (such as CAD).
Example: null
Branch Transit Number (5 digits). Provided only when the currency route requires it (such as CAD).
Example: null
Beneficiary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).
Example: null
Intermediary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).
Example: null
Faster Payment System identifier. Provided only when the currency route requires it (such as HKD).
Example: null
Response
application/json
{ "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88", "version": 123, "name": "My batch group", "sourceCurrency": "GBP", "status": "COMPLETED", "transferIds": [ 234, 456 ], "payInDetails": [ { "type": "bank_transfer", "reference": "B5323", "amount": 12504.54, "currency": "NOK", "name": "TransferWise Ltd", "branchName": null, "accountNumber": "9910728", "accountType": null, "bankCode": "8301", "bankAddress": { … }, "transferWiseAddress": { … }, "iban": null, "bban": "83019910728", "institutionNumber": null, "transitNumber": null, "beneficiaryBankBIC": null, "intermediaryBankBIC": null, "fpsIdentifier": null, "clearingNumber": null } ] }
Request
Create a transfer in the batch group using a previously created recipient account and quote.
For the request body format, see transfer creation. For quote and recipient creation, see quote creation and recipient creation.
Security
UserToken or PersonalToken
Unique identifier you generate for this transfer attempt.
Example: "a]1b2c3d4-e5f6-7890-abcd-ef1234567890"
Transfer purpose code.
Example: "verification.transfers.purpose.pay.bills"
Sub-purpose code for the transfer.
Example: "verification.sub.transfers.purpose.pay.interpretation.service"
- Production Environmenthttps://api.wise.com/v3/profiles/{profileId}/batch-groups/{batchGroupId}/transfers
- Sandbox Environmenthttps://api.wise-sandbox.com/v3/profiles/{profileId}/batch-groups/{batchGroupId}/transfers
curl -i -X POST \
https://api.wise.com/v3/profiles/12345678/batch-groups/54a6bc09-cef9-49a8-9041-f1f0c654cd88/transfers \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"targetAccount": 67890,
"sourceAccount": 12345,
"quoteUuid": "bd244a95-dcf8-4c31-aac8-bf5e2f3e54c0",
"customerTransactionId": "a]1b2c3d4-e5f6-7890-abcd-ef1234567890",
"details": {
"reference": "to my friend",
"transferPurpose": "verification.transfers.purpose.pay.bills",
"transferPurposeSubTransferPurpose": "verification.sub.transfers.purpose.pay.interpretation.service",
"sourceOfFunds": "verification.source.of.funds.other"
}
}'Transfer created successfully. Returns a transfer object.
object
Transfer object. See Transfer API reference for full details.
Response
application/json
{}
Request
Funds all transfers in a batch group from a multi-currency account balance. Transfers are paid out immediately.
The batch group must first be completed, and there must be enough funds in the account for the whole batch. Otherwise, an insufficient funds error will be returned.
This endpoint is SCA protected when it applies. If your profile is registered within the UK and/or EEA, SCA most likely applies to you. For more information, please read implementing SCA.
Security
UserToken or PersonalToken
- Production Environmenthttps://api.wise.com/v3/profiles/{profileId}/batch-payments/{batchGroupId}/payments
- Sandbox Environmenthttps://api.wise-sandbox.com/v3/profiles/{profileId}/batch-payments/{batchGroupId}/payments
curl -i -X POST \
https://api.wise.com/v3/profiles/12345678/batch-payments/54a6bc09-cef9-49a8-9041-f1f0c654cd88/payments \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"type": "BALANCE"
}'Batch group funded successfully.
If this batch was submitted as a file, this is the given file name.
Example: null
The source currency of the batch. Note that if there are insufficient funds, an automatic conversion from another currency can occur.
Example: "GBP"
Current batch group status.
Enum"NEW""COMPLETED""MARKED_FOR_CANCELLATION""PROCESSING_CANCEL""CANCELLED"
Example: "COMPLETED"
Whether this batch was submitted over the API or as a file.
Enum"API""FILE"
Example: "API"
Response
application/json
{ "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88", "name": "My batch group", "fileName": null, "alreadyPaid": true, "shortId": 12345, "userId": 33333333, "profileId": 44444444, "sourceCurrency": "GBP", "status": "COMPLETED", "groupType": "API", "transferIds": [ 100001, 100002, 100003 ] }
Request
Funds all transfers in a batch group via direct debit. The batch group must be in the COMPLETED state.
To use this funding method, you need to link an external bank account first. See direct debit account creation for more information.
This endpoint is SCA protected when it applies. If your profile is registered within the UK and/or EEA, SCA most likely applies to you. For more information, please read implementing SCA.
Security
UserToken or PersonalToken
Direct debit account ID. See direct debit account creation.
Example: 1
- Production Environmenthttps://api.wise.com/v1/profiles/{profileId}/batch-groups/{batchGroupId}/payment-initiations
- Sandbox Environmenthttps://api.wise-sandbox.com/v1/profiles/{profileId}/batch-groups/{batchGroupId}/payment-initiations
curl -i -X POST \
https://api.wise.com/v1/profiles/12345678/batch-groups/54a6bc09-cef9-49a8-9041-f1f0c654cd88/payment-initiations \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"type": "DIRECT_DEBIT",
"accountId": 1,
"reference": "B1234567"
}'Payment initiation created successfully. You need to save payment initiation ID for tracking its status later.
Payment reference that will be passed to the network. Can be used for reconciliation.
Example: "B1234567"
Payment initiation status:
NEW— Payment initiation createdPROCESSING— Payment is being processedCOMPLETED— Payment completed successfullyFAILED— Payment failedCHARGED_BACK— Payment was charged back
Enum"NEW""PROCESSING""COMPLETED""FAILED""CHARGED_BACK"
Example: "NEW"
Transfer ID of the direct debit payment. Present only after the direct debit is initiated.
Example: null
Response
application/json
{ "id": 12345, "batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0", "reference": "B1234567", "userId": 33333333, "profileId": 44444444, "type": "DIRECT_DEBIT", "status": "NEW", "accountId": 1, "transferId": null, "createdTime": "2022-01-01T19:51:41.423404Z" }
Request
Get payment initiation info by ID. In addition to webhooks, this endpoint can be used for polling the status of a payment initiation.
Security
UserToken or PersonalToken
- Production Environmenthttps://api.wise.com/v1/profiles/{profileId}/batch-groups/{batchGroupId}/payment-initiations/{paymentInitiationId}
- Sandbox Environmenthttps://api.wise-sandbox.com/v1/profiles/{profileId}/batch-groups/{batchGroupId}/payment-initiations/{paymentInitiationId}
curl -i -X GET \
https://api.wise.com/v1/profiles/12345678/batch-groups/54a6bc09-cef9-49a8-9041-f1f0c654cd88/payment-initiations/12345 \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Payment initiation retrieved successfully.
Payment reference that will be passed to the network. Can be used for reconciliation.
Example: "B1234567"
Payment initiation status:
NEW— Payment initiation createdPROCESSING— Payment is being processedCOMPLETED— Payment completed successfullyFAILED— Payment failedCHARGED_BACK— Payment was charged back
Enum"NEW""PROCESSING""COMPLETED""FAILED""CHARGED_BACK"
Example: "NEW"
Transfer ID of the direct debit payment. Present only after the direct debit is initiated.
Example: null
Response
application/json
{ "id": 12345, "batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0", "reference": "B1234567", "userId": 33333333, "profileId": 44444444, "type": "DIRECT_DEBIT", "status": "NEW", "accountId": 1, "transferId": null, "createdTime": "2022-01-01T19:51:41.423404Z" }
Bulk Settlement
Bulk settlement allows partners to settle multiple transfers in a single bank transfer at the end of a settlement period. This model splits transfer creation/funding from final settlement, allowing Wise to process transfers before receiving funds based on a partner's guarantee.
Use the settlement journal endpoint to submit a list of transfers to be settled, along with the settlement reference that matches your bank transfer payment.
Operations
Card
Manage your customers' cards programmatically. These APIs allow you to retrieve card details, control card status, manage spending permissions, and access sensitive card data securely.
Key capabilities:
- List and retrieve card details for a profile
- Update card status (active, frozen, blocked)
- Control spending permissions (e-commerce, ATM, contactless, etc.)
- Access sensitive card data (PAN, CVV, PIN) via encrypted JWE payloads
Sensitive card details: Wise is a PCI DSS compliant provider and stores all card data securely. The scope for PCI compliance depends on your use case and will impact how you integrate. For all sensitive card details endpoints, follow the detailed guide.
For ordering new cards, see the Card Order API. For transaction history, see the Card Transaction API.
SchemasOperations
Card Kiosk Collection
These APIs are designed to allow you to print and encrypt your card directly from a kiosk machine. The card information will be sent to our card manufacturer to configure and print the card on-site on a kiosk machine.
The card printing process will automatically begin once the request is received by our card manufacturer.
During the printing process, you will be notified via webhook about any card production status change.
Before using these APIs, make sure to read the guide on kiosk collection.
Please reach out to your Implementation Manager for more information on these APIs.
Testing: In the sandbox environment, use the card production simulation API to test your integration with various production statuses and error scenarios.
Production status flow
These statuses represent the lifecycle of a card production:
READY- Card is ready for production. The produce card endpoint can be called.IN_PROGRESS- Card is being produced at the kiosk machine (chip encryption and printing in progress).PRODUCED- Card has been successfully produced and collected from the kiosk. This is a final state.PRODUCTION_ERROR- Card production failed. Check the errorCode to identify the issue, resolve it, then retry using the produce card endpoint.
A card with production status PRODUCED will trigger an asynchronous call to update the associated card order to PRODUCED status.
Operations
Card Order
With this set of APIs, you will be able to create cards for your customers. You can also retrieve and view the status of your current card orders, as well as the list of available card programs for the user.
On production, each personal profile can order at most 1 physical card and 3 virtual cards. On sandbox, we allow up to 10 physical cards and 30 virtual cards for testing purpose. However, no more than 3 virtual cards can be ordered per day. This limit includes cards and card orders.
Card order status flow
The card order response will contain the status field. The initial status is PLACED or REQUIREMENTS_FULFILLED depending on the requirement fulfillment state:
PLACED- The card order is created. The card will be generated once it has fulfilled all the requirementsREQUIREMENTS_FULFILLED- The card order has fulfilled all the requirements and the card should be generated in a short whileCARD_DETAILS_CREATED- The card has been generatedPRODUCED- The physical card has been produced and waiting to be picked up by delivery vendor (physical card only)COMPLETED- The card has been activated and is ready to use. The card order is completedCANCELLED- The card order has been cancelled. This can happen if you reach out to Wise Support to cancel a card orderRETURNED- Delivery failed, the physical card has been returned and will be blocked (physical card only)
SchemasOperations
Card Transaction
Retrieve information on transactions made on your users' cards.
Transaction types
The possible type values are:
ACCOUNT_CREDIT- Receiving money on the card, excluding Visa OCT or Mastercard MoneySendACCOUNT_FUNDING- Sending money to another card or e-walletCASH_ADVANCE- Cash disbursementCASH_WITHDRAWAL- ATM withdrawalCHARGEBACK- Currently unused. Reserved for future useCREDIT_TRANSACTION- Visa OCT and Mastercard MoneySendECOM_PURCHASE- Online purchasePOS_PURCHASE- Purchase via a POS terminalREFUND- Partial or full refund of an existing card transaction
Transaction states
The possible state values are:
IN_PROGRESS- The transaction has been authorized but not capturedCOMPLETED- The transaction has been captured and/or settledDECLINED- The transaction has been declinedCANCELLED- The transaction has been cancelledUNKNOWN- Default fallback status if the state cannot be confirmed
The transition from CANCELLED to COMPLETED is an edge case. Wise releases the customer funds after 7 days (30 days for pre-authorization) if the merchant has not captured the transaction, and the state becomes CANCELLED. However, the merchant can decide to capture the transaction at a later date, at which point the state will become COMPLETED.
Decline reasons
The decline reason field provides information about the specific issue that led to the transaction being declined, helping the merchant and the customer troubleshoot the problem.
While the decline reason field provides valuable information, it may not cover all possible reasons for a decline, such as technical issues or unforeseen circumstances.
New decline reasons may be added in the future, and not all decline reasons are currently documented. Review this documentation regularly to ensure accuracy.
Exercise caution when communicating decline reasons to your customers, as some may not be relevant or may cause confusion.
ACCOUNT_INACTIVE- Balance related to the transaction is not active. Ensure that all outstanding actions have been completed before using the card, as this may help avoid potential issues or declinesACCOUNT_SUSPENDED- The transaction has been declined pending further compliance checks. It may have been flagged for potential sanctions issuesATM_PIN_CHANGE_NOT_ALLOWED- PIN change via ATM terminal is not allowedBLOCKED_COUNTRY- Transactions were made in unsupported countries. Check this link to see if the country is included in the list of supported nations. It is possible for a merchant to be based in a supported country and have an address registered in a blocked country, albeit infrequentlyBLOCKED_SUBSCRIPTION- The system cannot facilitate this transaction as the customer has opted out of recurring payments with this merchantCARD_EXPIRED- The card provided has reached its expiration date, making it invalid for this transactionCARD_FROZEN- The customer or the customer service team has put this card on a temporary hold. If the card has not been frozen by the customer, it may be worth investigating further. To resume spending, advise the customer to unfreeze the cardCARD_INACTIVE- The card is either not active or has not been received by the customer, so the transaction cannot proceedCARD_BLOCKED- The card has been blocked and cannot be used anymoreCARD_PARTNER_SUSPENDED- The internal team has deactivated the account for compliance reasons related to AML, fraud, or EDD. Contact the team if this is believed to be an errorCHIP_PIN_ENTRY_TRIES_EXCEEDED- The PIN is restricted on the chip of the card due to excessive incorrect entries. The blocked PIN can be unlocked at an ATM using specific steps that vary depending on the machine and country, such as PIN management or PIN operations followed by unblocking the PINCONNECTION_ISSUE- A connection problem occurred during the transactionCONTACTLESS_PIN_ENTRY_REQUIRED- Contactless payment systems sometimes require a PIN for authentication purposes to protect users' accounts from potential fraud or tampering. In Europe, contactless payment transactions that follow one after the other require PIN verification as an additional security measureCREDIT_TRANSACTIONS_NOT_SUPPORTED- Credit is not supported for this specific transaction. Review the Acceptable Use Policy for further informationCUMULATIVE_LIMIT_EXCEEDED- In certain jurisdictions, there are restrictions on the amount that can be spent. Refer to spending limits for further detailsDECLINED_ADVICE- There is a problem with the message from the processor, so it might not be accepted because it could be incomplete or unsafe. This does not indicate a problem with the card. Advise the customer that there was a technical issue with the payment and to try again laterINCORRECT_CVV- The customer entered the wrong security code. Advise the customer to check their card details and try again. If the saved card details are correct, they should remove their card details from the merchant's website and add them back againINCORRECT_EXPIRY_DATE- The customer entered the wrong expiration date for their card. If the saved card details are correct, they should remove their card details from the merchant's website and add them back againINCORRECT_PIN- The customer entered their PIN incorrectly. Advise the customer to check their PIN and try again. If the PIN is correct and still fails, suggest resetting the PININSUFFICIENT_FUNDS- The customer does not have enough money in their account to make the payment. Advise the customer to add money to their account and try again. In most cases, this will resolve the issueINVALID_3DS_UCAF- The 3D Secure checks failed during the transaction. The customer should try again and request authenticationINCORRECT_ARQC- ARQC (Authorization Request Cryptogram) is a cryptogram generated by the card during a transaction, which is validated on the server side. If incorrect, it could indicate a faulty card, a fraudulent attack, or an issue with the POS terminalINCORRECT_ICVV- ICVV (Integrated Circuit Card Verification Value) is a security feature used to validate the authenticity of a card during chip-based transactions. There were problems reading the chip on the card, which may indicate an issue with the card's chip, the terminal, or the transaction process. Wait and try againINVALID_MERCHANT- Transaction from a specific merchant is declined by scheme. The merchant should clarify the exact cause with the schemeINVALID_TRANSACTION- Certain types of transactions are not supported. The customer should ask the merchant to use a different payment method or try a different merchantMANDATE_DCC_NON_SUPPORTED_FOR_CARD_COUNTRY- The transaction was declined because the system does not support conversions for Brazilian cards when BRL is involved. BRL will not be automatically exchanged to other currencies. If the customer wants to continue with the payment, they need to change the currencyMANDATE_LOCAL_CASH_WITHDRAWAL_NOT_ALLOWED- ATM withdrawal services are not provided in the country where the transaction is taking placeNON_SUPPORTED_CURRENCY- The currency in this transaction is not supportedNON_SUPPORTED_MCC_FOR_COUNTRY- Transactions in this category are not supported for customers in the country of purchase. Consider using an alternative payment method or changing merchantPAYMENT_METHOD_DAILY_LIMIT_EXCEEDED- The customer has reached the daily spending limit for the card or their profile. Advise if they would like to update card or profile limitPAYMENT_METHOD_LIFETIME_LIMIT_EXCEEDED- The customer has reached the lifetime spending limit. Advise if they would like to increase their lifetime limitPAYMENT_METHOD_MONTHLY_LIMIT_EXCEEDED- The customer has reached the monthly spending limit for the card or their profile. Advise if they would like to update card or profile limitPAYMENT_METHOD_NOT_ALLOWED- This payment type has been disabled. Advise if they would like to enable the payment typePAYMENT_METHOD_TRANSACTION_LIMIT_EXCEEDED- The customer has exceeded the transaction limit for the card. Advise if they would like to update their card limitPIN_ENTRY_TRIES_EXCEEDED- The customer has reached the maximum number of allowed online PIN entry attempts. Consider implementing a reset PIN feature within the app to help the customer regain access to their cardPRE_ACTIVATED_CARD_PIN_ENTRY_REQUIRED- The customer has attempted to make a contactless payment at a POS or ATM, but their card has not been activated for chip and PIN transactions. To modify the card activation strategy for all cards, contact the implementation managerPROCESSING_ERROR- The system is currently experiencing technical difficulties. Advise the customer to try again after a brief periodRESTRICTED_MODE- Although rare, restricted mode can occur. Advise the customer to replace their card promptly as the system should have already informed them. In this mode, more secure payment methods like chip and PIN, contactless, mobile wallets, and online payments with 3DS are allowed, while less secure methods like magnetic stripe and online payments without 3DS are not permittedREVERSAL_NOT_MATCHING_AUTH_CURRENCY- The merchant has issued a reversal instruction for a different currency than what was originally requested during the authorization processSCA_SOFT_DECLINE- The transaction cannot proceed due to SCA regulations. Suggest the customer contact the merchant and use a more secure authentication method such as 3DS. For example, the customer can try chip and PIN, or a mobile wallet like Apple Pay or Google PaySCHEME_BLOCKED_TRANSACTION- This transaction has been flagged by the scheme and cannot be processedSECURITY_CVM_FAILURE- The system has detected that the POS terminal was misconfigured and failed security checks. Suggest the customer use an alternative payment method like contactless or mobile wallets, or recommend asking the merchant to accept a signature insteadSECURITY_MAGSTRIPE_SECURE_ELEMENTS_INCORRECT_OR_MISSING- The merchant has entered the wrong type of purchase. Advise the customer to contact the merchant and ask them to correct this issueSECURITY_PIN_ENTRY_REQUIRED- To proceed with this transaction, the customer is required to enter their PINSUSPECTED_FRAUD- This transaction has been labeled as high-risk by WiseSUSPECTED_FRAUD_AML- This transaction has been flagged as high-risk based on AML compliance protocols. This reason cannot be disclosed to end customersSUSPECTED_FRAUD_COMPLIANCE- The compliance system has flagged this transaction as high-risk. This reason cannot be disclosed to end customersSUSPECTED_FRAUD_CORE_FRAUD- This transaction has been blocked based on fraud policies and proceduresSUSPECTED_FRAUD_SANCTIONS- This transaction has been flagged as high-risk based on sanctions list analysis. This reason cannot be disclosed to end customers. This classification is final and cannot be appealedSUSPECTED_FRAUD_SOFT_DECLINE- This e-commerce transaction cannot be processed due to high risk factors. The merchant must complete 3DS before the transaction can be approvedTRANSACTION_TYPE_NOT_SUPPORTED- There are restrictions on this type of transaction, and sometimes the scheme will not allow it. Check if spend control is set up to block this transactionUNEXPECTED_ERROR- There may have been a communication error between the merchant's system and the server, but the POS system may have already notified the user of this issue
Operations