Transfers API v2024-06-01 Use Case Guide
How to initiate payouts using the Transfers API.
Note
The Transfers API v2024-06-01 API is only available in private beta.
API Version: 2024-06-01
What is the Transfers API?
Sellers can use the Transfers API v2024-06-01 API to initiate payouts to a seller's deposit method on file and retrieve information about the payment instruments associated with a seller.
What is in this guide?
This guide describes how to use the Transfers API v2024-06-01 API to request a payout of an available balance and retrieve the seller's payment method and details for the given marketplace and account type.
Tutorial 1: Initiate a payout
This tutorial demonstrates how to initiate a payout to the seller's deposit method. Only one on-demand payout can be initiated for each marketplace and account type within a 24-hour period.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
- Approval for the Finance and Accounting role in your developer profile.
- The Finance and Accounting role selected in the app registration page for your application.
Step 1. Call the initiatePayout operation with the following parameters
initiatePayout operation with the following parametersBody parameters
| Name | Description | Schema | Required |
|---|---|---|---|
initiatePayoutRequest | The request body for the initiatePayout operation. | InitiatePayoutRequest | Yes |
Request
| Name | Description | Schema | Required |
|---|---|---|---|
marketplaceId | A marketplace identifier. Only supported in the following marketplaces: ES, FR, BE, NL, DE, IT, SE, PL (refer to Marketplace IDs). | string | Yes |
accountType | The account type in the selected marketplace for which a payout has to be initiated. For the supported EU marketplaces, the only account type is Standard Orders. | string | Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/finances/transfers/2024-06-01/payouts/
{
"marketplaceId": "A1PA6795UKMFR9",
"accountType": "Standard Orders"
}
Response
A successful response includes the following:
| Name | Description | Schema |
|---|---|---|
payoutReferenceId | A successful payout initiation result includes a payoutReferenceId that can be used by selling partners to track payout information. It is the financial event group ID for an initiated payout. | string |
Response example
{
"payoutReferenceId": "3DM7DQi8DPAMOLOSaN5HxT0q2waNwH95fopx3XXXXxx"
}
Error
An unsuccessful response includes a list of errors describing the reasons why a payout is not initiated.
| Error | Description | Schema |
|---|---|---|
coderequired | An error code that identifies the type of error that occurred. Example: "InvalidInput" | string |
messagerequired | A message that describes the error condition in a human-readable form. Example: "The input request had one or more invalid input parameters." | string |
detailsoptional | Additional details that can help the caller understand or fix the issue. Example: "The following input parameters are invalid : [marketplaceId]." | string |
Response example
{
"errors": [
{
"code": "NO_DEPOSIT_METHOD",
"message": "Deposit method is missing, invalid or not assigned."
},
{
"code": "INSUFFICIENT_PAYOUT_AMOUNT",
"message": "Available balance is below the minimum allowed payout amount."
}
]
}
Tutorial 2: Retrieve payment instrument details associated with a seller
This tutorial demonstrates how to retrieve the list of payment methods added by the seller, along with details of the marketplaces where each payment method is being used for payouts.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
- Approval for the Finance and Accounting role in your developer profile.
- The Finance and Accounting role selected in the app registration page for your application.
- A basic understanding of the Selling Partner API.
- The marketplace identifier for the marketplace for which to return data. For the list of possible marketplace identifiers, refer to Marketplace IDs.
Step 1. Call the getPaymentMethods operation with the following parameters to get details of payment instruments associated with a seller
getPaymentMethods operation with the following parameters to get details of payment instruments associated with a sellerBody parameters
| Name | Description | Schema | Required |
|---|---|---|---|
owningCustomerId | The customer ID of the seller | string | Yes |
marketplaceId | The marketplace identifier | string | Yes |
requestId | The unique request reference identifier | string | No |
paymentMethodFilter | The object used to filter payment methods based on different factors. | PaymentMethodFilter | No |
Request example
POST https://sellingpartnerapi-na.amazon.com/paymentInstruments/2024-06-11/paymentMethods
{
"owningCustomerId": "A3IV0OPJ9VFD0U",
"marketplaceId": "ATVPDKIKX0DER",
"requestId": "Rufus",
"paymentMethodFilter": {
"subscribedMarketplaces": [
"ATVPDKIKX0DER"
],
"assignmentFilter": {
"assignmentTypes": [
"DEFAULT"
]
}
}
}
Response
| Name | Description | Schema |
|---|---|---|
countryCode | The two-letter country code that follows the ISO 3166-1 alpha-2 standard. For payment methods in the card category, the code is for the country where the card was issued. For payment methods in the bank account category, the code is for the country where the account is located. | string |
defaultMarketplaces | The list of marketplaces where the the payment instrument is marked as default. The selected payment instrument activates payouts for these marketplaces. | string |
encryptedAccountHolderName | The encrypted account holder name that is registered for the payment instrument. | string |
paymentInstrumentId | The payment instrument identifier. | string |
paymentInstrumentType | The payment instrument type. | string |
tail | The last three or four digits of the payment instrument. | string |
expiryDate | The expiration date of a card used for payment. | ExpiryDate |
Response example
{
"piDetails": [
{
"countryCode": "US",
"defaultMarketplaces": [
"ATVPDKIKX0DER"
],
"encryptedAccountHolderName": "?SIEGE|Rufus!00AAAAAAYIARAAGgAAAAAADgjowvyyBhAAGAAgADIAAAAAkQAAAAAAAAAA1goTnyZO5d+yqPgsktNT/nEAAAAAAAAAP0MonpF3YDVi4nembq6SlQ+4vdiDYdw3yAQnHXMw7xQtF7vzrLY/MJPd3nisz3cIf8mXj5Q6OLDmVukyrqBS0ZDq12OuNAqwh3O1w/tAba31f7UBWfhg3XJFwflqHOX028hd7wmGl72o9NNk6ylY18g=!EGEIS?",
"paymentInstrumentId": "0h_XX_XXX_4058fe2a-da6b-4b82-8e48-b20ff2eb4f6d",
"paymentInstrumentType": "BANK_ACCOUNT",
"tail": "677"
},
{
"countryCode": "US",
"defaultMarketplaces": [],
"encryptedAccountHolderName": "?SIEGE|Rufus!00AAAAAAYIARAAGgAAAAAADgifhKSzBhAAGAAgADIAAAAAkQAAAAAAAAAA+aXar1F9ra7QKkr0NkMsJ3EAAAAAAAAA5ymt72t/8oo92yIncF9N9mJjjJa6al4Q2UWqPARfE7+J/F4adHW/TlOR9HjValBdJkVO7HDS+10+iGAISEShiRdZ4zW+KaFuho8azqk3gpHOQIK6zfnzQpe6Vd+Og5LnbDLoIIqyg3gB0xkh/zbEHrw=!EGEIS?",
"expiryDate": {
"month": "4",
"year": "2027"
},
"paymentInstrumentId": "0h_PU_CUS_a401314d-b87d-4015-a4ca-e452c7b6ac7d",
"paymentInstrumentType": "CARD",
"tail": "5170"
}
]
}
Updated 3 days ago