Transfers API v2024-06-01 reference

Overview

The Selling Partner API for Transfers enables the selling partners to initiate payouts for their seller accounts. This API is only available in private beta.

Version information

Version : 2024-06-01

Contact information

Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html

License information

License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0

URI scheme

Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS

Consumes

application/json

Produces

application/json

Operations

initiatePayout
getPaymentMethods

Paths

POST /finances/transfers/2024-06-01/payouts

Operation: initiatePayout

Description

Initiates on demand payout to the seller's default deposit method in SellerCentral for the given marketplaceId and accountType (if eligible). In a rolling 24 hours period, only one on-demand payout is allowed to be initiated for a marketplace and account type.

Usage Plan:

Rate (requests per second)	Burst
0.5	30

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

Type	Name	Description	Schema
Body	body required	Request body for InitiatePayout operation.	InitiatePayoutRequest

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	InitiatePayoutResponse
400	Request has missing or invalid parameters and cannot be parsed. Possible values include: INVALID_INPUT: The marketplaceId/accountType provided in the input is invalid. NOT_ELIGIBLE_FOR_ON_DEMAND_PAYOUT: The seller is not eligible for On-Demand Payouts. Retries would most likely fail. NO_DEPOSIT_METHOD: No deposit method found for the selling partner. Please add a valid deposit method and try again. INSUFFICIENT_PAYOUT_AMOUNT: The outstanding balance is less than the minimum permissible payout amount, hence no payout will be initiated. PAYOUT_FREQUENCY_EXCEEDED: This occurs if there has already been a payout initiated for the given marketplace and accountType in the last 24 hours. A selling partner can request payout once in every 24 hours for a given marketplace and accountType. Note: The error codes listed here are not an exhaustive representation. The API's error handling is subject to change, and additional error codes may be introduced in the future. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	ErrorList

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Example HTTP request

Request body

{
  "marketplaceId" : "APJ6JRA9NG5V4",
  "accountType" : "Standard Orders"
}

Example HTTP response

Response 200

{
  "payoutReferenceId" : "3DM7DQi8DPAMOLOSaN5HxT0q2waNwH95fopx3AD2Lgc"
}

POST /finances/transfers/2024-06-01/paymentmethods

Operation: getPaymentMethods

Description

Get list of payment instruments added for a particular seller.These payment instruments can be used for payouts.

Parameters

Type	Name	Description	Schema
Body	body required	The request schema of GetPaymentMethods operation.	GetPaymentMethodsRequest

Responses

HTTP Code	Description	Schema
200	Success Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	GetPaymentMethodsResponse
400	Request has missing or invalid parameters and cannot be parsed. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	ErrorList

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Example HTTP request

Request body

{
  "owningCustomerId" : "ACUULBDVZHYZZ",
  "marketplaceId" : "ATVPDKIKX0DER",
  "requestId" : "Rufus",
  "paymentMethodFilter" : {
    "subscribedMarketplaces" : [ "ATVPDKIKX0DER" ],
    "assignmentFilter" : {
      "assignmentTypes" : [ "DEFAULT" ]
    }
  }
}

Example HTTP response

Response 200

{
  "piDetails" : [ {
    "countryCode" : "US",
    "defaultMarketplaces" : [ "ATVPDKIKX0DER" ],
    "encryptedAccountHolderName" : "?SIEGE|Rufus!00AAAAAAYIARAAGgAAAAAADgjowvyyBhAAGAAgADIAAAAAkQAAAAAAAAAA1goTnyZO5d+yqPgsktNT/nEAAAAAAAAAP0MonpF3YDVi4nembq6SlQ+4vdiDYdw3yAQnHXMw7xQtF7vzrLY/MJPd3nisz3cIf8mXj5Q6OLDmVukyrqBS0ZDq12OuNAqwh3O1w/tAba31f7UBWfhg3XJFwflqHOX028hd7wmGl72o9NNk6ylY18g=!EGEIS?",
    "paymentInstrumentId" : "0h_TU_CUS_4058fe2a-da6b-4b82-8e48-b20ff2eb4f6d",
    "paymentInstrumentType" : "CARD",
    "expiryDate" : {
      "month" : "3",
      "year" : "2029"
    },
    "tail" : "677"
  } ]
}

Error Responses and Schemas

This table contains HTTP status codes and associated information for error responses.

HTTP Code	Description	Schema
403	Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
404	The resource specified does not exist. Headers: `x-amzn-RateLimit-Limit` (string):Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
413	The request size exceeded the maximum accepted size. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
415	The request payload is in an unsupported format. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
429	The frequency of requests was greater than allowed. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
500	An unexpected condition occurred that prevented the server from fulfilling the request. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
503	Temporary overloading or maintenance of the server. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList

Definitions

InitiatePayoutRequest

The request schema for the initiatePayout operation.

Name	Description	Schema
marketplaceId required	A marketplace identifier. Refer to Marketplace IDs for the list of possible marketplace identifiers.	string
accountType required	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

InitiatePayoutResponse

The response schema for the initiatePayout operation.

Name	Description	Schema
payoutReferenceId required	In case of a successful payout initiation, the result contains a payoutReferenceId that can be used by selling partners to track payout information. It is the Financial Event Group ID for which a payout has been initiated.	string

GetPaymentMethodsRequest

The request schema for the getPaymentMethods operation.

Name	Description	Schema
owningCustomerId optional	CustomerId of the seller.	StringWithNoWhiteSpace
marketplaceId optional	An identifier for the marketplace.	StringWithNoWhiteSpace
requestId optional	Unique request reference identifier.	StringWithNoWhiteSpace
paymentMethodFilter optional	Represents an object to filter payment instrument based on different factors.	PaymentMethodFilter

GetPaymentMethodsResponse

The response schema for the getPaymentMethodsResponse operation.

Name	Description	Schema
piDetails optional	Contains list of Payment Instruments.	ListOfPIDetails

PaymentMethodFilter

Represents an object to filter payment instrument based on different factors.

Name	Description	Schema
paymentInstrumentId optional	Identifier of a payment instrument.	StringWithNoWhiteSpace
subscribedMarketplaces optional	Contains list of marketplaces for which the payout instrument is required.	ListOfStrings
assignmentFilter optional	Represents filter to return default payment instrument(s).	AssignmentFilter
paymentInstrumentTypes optional	List of types of payment instrument.	ListOfPaymentInstrumentType

AssignmentFilter

Returns default payment instrument(s) only as per the assignmentFilter value.

Name	Description	Schema
assignmentTypes optional	Represents List of Assignment Types.	ListOfAssignmentType

ListOfAssignmentType

Represents List of Assignment Types.

Type : < AssignmentType > array

AssignmentType

Filters payment methods based on the type of assignment.

Type : enum

Value	Description
DEFAULT	Payment instrument used as primary payout method.

ListOfPIDetails

Contains list of Payment Instruments.

Type : < PIDetails > array

PIDetails

This object represents details of a payment instrument.

Name	Description	Schema
encryptedAccountHolderName optional	Encrypted Account Holder name with which payment instrument is registered.	StringWithNoWhiteSpace
paymentInstrumentId optional	Identifier of a payment instrument.	StringWithNoWhiteSpace
tail optional	The last 3/4 digits of the payment instrument.	StringWithDigits
expiryDate optional	Represents expiry date of a card.[Modify]	ExpiryDate
countryCode optional	2-letter country code following ISO 3166-1 alpha-2 standard. For Payment Methods with category Card, this is the country where the card was issued. For Payment Methods with category Bank Account, this is the country where the account is located.	StringWithNoWhiteSpace
defaultMarketplaces optional	List of marketplace where payment instrument is marked as Default. Payouts for a marketplace will be triggered corresponding to default payment instrument.	ListOfStrings
paymentInstrumentType optional	Represents type of payment instrument.	PaymentInstrumentType

ExpiryDate

This field represents expiry date if the given payment instrument is a card. Nullable in case payment instrument is not card.

Name	Description	Schema
month optional	Month	StringWithDigits
year optional	Year	StringWithDigits

ListOfPaymentInstrumentType

Returns only those payment instruments whose types are present in this list.

Type : < PaymentInstrumentType > array

PaymentInstrumentType

Type of Payment Instrument.

Type : enum

Value	Description
BANK_ACCOUNT	Bank Account.
CARD	Card
SELLER_WALLET	Seller Wallet Virtual Bank Account.

ListOfStrings

List of Strings.

Type : < StringWithNoWhiteSpace > array

StringWithDigits

Strings with Digits.

Type : string

Pattern : ^[0-9]*

StringWithNoWhiteSpace

String with No White Spaces.

Type : string

Pattern : \S+

ErrorList

A list of error responses returned when a request is unsuccessful.

Name	Description	Schema
errors required	array of errors Example : `[ {<br> "code" : "InvalidInput",<br> "message" : "The input request had one or more invalid input parameters."<br>} ]`	< Error > array

Error

Error response returned when the request is unsuccessful.

Name	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. 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