Transfers API v2024-06-01 Use Case Guide

How to retrieve payment methods and initiate payouts using the Transfers API.

API Version: v2024-06-01

This guide describes how to use the Transfers API v2024-06-01 to retrieve the seller's payment methods and request a payout of an available balance for the given marketplace and account type.

What is the Transfers API?

Sellers can use the Transfers API v2024-06-01 to retrieve information about the payment methods associated with a seller and initiate payouts to a seller's deposit method on file.

Tutorial 1: Retrieve payment method details associated with a seller

This tutorial demonstrates how to retrieve the list of payment methods added by the seller for a given marketplace.

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. Get details of payment methods associated with a seller in a given marketplace

Call the getPaymentMethods operation with the following parameters:

Query parameters

Name	Description	Schema	Required
`marketplaceId`	The identifier of the marketplace from which you want to retrieve payment methods. To find the ID for your marketplace, refer to Marketplace IDs.	string	Yes
`paymentMethodTypes`	A comma-separated list of the payment method types you want to include in the response.	< string > array	No

Request examples

GET /finances/transfers/2024-06-01/paymentMethods?marketplaceId=ATVPDKIKX0DER

GET /finances/transfers/2024-06-01/paymentMethods?marketplaceId=ATVPDKIKX0DER?paymentMethodTypes=BANK_ACCOUNT,CARD

Response

Name	Description	Schema
`accountHolderName`	The name of the account holder that is registered for the payment method.	string
`paymentMethodId`	The identifier of the payment method.	string
`paymentMethodType`	The type of payment method.	`PaymentMethodType`
`tail`	The last three or four digits of the payment method.	string
`assignmentType`	The default payment method type. This field is equal to `DEFAULT_DEPOSIT_METHOD` if the payment method is your default deposit method.	`AssignmentType`
`countryCode`	The two-letter country code in ISO 3166-1 alpha-2 format. 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
`expiryDate`	The expiration date of a card used for payouts.	`ExpiryDate`

Response example

{
  "paymentMethods": [
    {
      "accountHolderName": "John Doe",
      "paymentMethodId": "0h_TU_CUS_4058fe2a-da6b-4b82-8e48-b20ff2eb4f6d",
      "paymentMethodType": "BANK_ACCOUNT",
      "tail": "677",
      "assignmentType": "DEFAULT_DEPOSIT_METHOD",
      "countryCode": "UK"
    },
    {
      "accountHolderName": "John Doe",
      "paymentMethodId": "0h_TU_CUS_4058fe2a-da6b-4b82-8e48-b20ff2eb4f6d",
      "paymentMethodType": "BANK_ACCOUNT",
      "tail": "677",
      "countryCode": "DE"
    }
  ]
}

Tutorial 2: 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. Initiate a payout

Call the initiatePayout operation. The request is of type InitiatePayoutRequest and includes the following parameters:

Body parameters

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 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 response

An unsuccessful response includes a list of errors describing the reasons why a payout is not initiated.

Error	Description	Schema
`code` required	An error code that identifies the type of error that occurred. Example: `"InvalidInput"`	string
`message` required	A message that describes the error condition in a human-readable form. Example: `"The input request had one or more invalid input parameters."`	string
`details` optional	Additional details that can help the caller understand or fix the issue. Example: `"The following input parameters are invalid : [marketplaceId]."`	string

Error response example

{
  "errors": [
    {
      "code": "NoDepositMethod",
      "message": "Deposit method is missing, invalid or not assigned."
    },
    {
      "code": "InsufficientPayoutAmount",
      "message": "Available balance is below the minimum allowed payout amount."
    }
  ]
}

Updated about 1 month ago