Hub per sviluppatoriStato dell'APISupporto

Guida ai casi d'uso di Transfers API v2024-06-01

Come recuperare i metodi di pagamento e avviare i pagamenti utilizzando l'API Transfers.

Versione API: v01-07-2020

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.

Cos'è l'API Transfers?

I venditori possono utilizzare il API di trasferimento v2024-06-01 per recuperare informazioni sui metodi di pagamento associati a un venditore e avviare i pagamenti utilizzando il metodo di deposito del venditore registrato.

Tutorial 1: Recupera i dettagli del metodo di pagamento associato a un venditore

Questo tutorial dimostra come recuperare l'elenco dei metodi di pagamento aggiunti dal venditore per un determinato marketplace.

Prerequisiti

Per completare correttamente questo tutorial, devi avere:

Fase 1. Ottieni dettagli sui metodi di pagamento associati a un venditore in un determinato marketplace

Chiama l'operazione getPaymentMethods con i seguenti parametri:

Parametri di query

NomeDescrizioneSchemaObbligatorio
marketplaceIdL'identificativo del marketplace da cui desideri recuperare i metodi di pagamento. Per trovare l'ID del tuo marketplace, consulta ID del Marketplace.string
paymentMethodTypesUn elenco separato da virgole dei tipi di metodo di pagamento che desideri includere nella risposta.< corda > matriceNo
Esempi di richieste
GET /finances/transfers/2024-06-01/paymentMethods?marketplaceId=ATVPDKIKX0DER GET /finances/transfers/2024-06-01/paymentMethods?marketplaceId=ATVPDKIKX0DER?paymentMethodTypes=BANK_ACCOUNT,CARD
Risposta
NomeDescrizioneSchema
accountHolderNameIl nome del titolare del conto registrato per il metodo di pagamento.string
paymentMethodIdL'identificatore del metodo di pagamento.string
paymentMethodTypeIl tipo di metodo di pagamento.PaymentMethodType
tailLe ultime tre o quattro cifre del metodo di pagamento.string
assignmentTypeIl tipo di metodo di pagamento predefinito. Questo campo è uguale a DEFAULT_DEPOSIT_METHOD se il metodo di pagamento è il tuo metodo di deposito predefinito.AssignmentType
countryCodeIl prefisso internazionale di due lettere in ISO 3166-1 alfa-2 formato. Per i metodi di pagamento in CARD categoria, il codice si riferisce al paese in cui è stata emessa la carta. Per i metodi di pagamento in BANK_ACCOUNT categoria, il codice si riferisce al paese in cui si trova l'account.string
expiryDateLa data di scadenza di una carta utilizzata per i pagamenti.ExpiryDate
Esempio di risposta
{ "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: Avvia un pagamento

Questo tutorial dimostra come avviare un pagamento con il metodo di deposito del venditore. È possibile avviare un solo pagamento su richiesta per ogni marketplace e tipo di account entro un periodo di 24 ore.

Prerequisiti

Per completare correttamente questo tutorial, devi avere:

Fase 1. Avvia un pagamento

Chiama il initiatePayout operazione. La richiesta è di tipo InitiatePayoutRequest e include i seguenti parametri:

Parametri del corpo

NomeDescrizioneSchemaObbligatorio
marketplaceIdUn identificativo del marketplace. Supportato solo nei seguenti marketplace: ES, FR, BE, NL, DE, IT, SE, PL (fare riferimento a ID del marketplace).string
accountTypeIl tipo di account nel marketplace selezionato per il quale deve essere avviato un pagamento. Per i marketplace UE supportati, l'unico tipo di account è Standard Orders.string

Esempio di richiesta

POST finances/transfers/2024-06-01/payouts/ { "marketplaceId": "A1PA6795UKMFR9", "accountType": "Standard Orders" }

Risposta

Una risposta con esito positivo include quanto segue:

NomeDescrizioneSchema
payoutReferenceIdUn risultato di avvio del pagamento riuscito include un payoutReferenceId che può essere utilizzato dai partner di vendita per tenere traccia delle informazioni sui pagamenti. È l'ID del gruppo di eventi finanziari per un pagamento avviato.string

Esempio di risposta

{ "payoutReferenceId": "3DM7DQi8DPAMOLOSaN5HxT0q2waNwH95fopx3XXXXxx" }

Risposta all'errore

Una risposta non riuscita include un elenco di errori che descrivono i motivi per cui un pagamento non viene avviato.

ErroreDescrizioneSchema
code
required
Un codice di errore che identifica il tipo di errore che si è verificato.
Esempio: "InvalidInput"
string
message
required
Un messaggio che descrive la condizione di errore in un formato leggibile dall'uomo.
Esempio: "The input request had one or more invalid input parameters."
string
details
optional
Dettagli aggiuntivi che possono aiutare il chiamante a comprendere o risolvere il problema.
Esempio: "The following input parameters are invalid : [marketplaceId]."
string

Esempio di risposta all'errore:

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

Questa pagina ti è stata utile?