Transfers API v2024-06-01 Use Case Guide

📘

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

Body parameters

Request

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:

Response example

{
  "payoutReferenceId": "3DM7DQi8DPAMOLOSaN5HxT0q2waNwH95fopx3XXXXxx"
}

Error

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

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

Body parameters

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

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"
    }
  ]
}