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:
- Autorizzazione del partner di vendita per il quale stai effettuando chiamate. Per ulteriori informazioni, consulta Autorizzazione delle applicazioni Selling Partner API.
- Approvazione per Ruolo finanziario e contabile nel tuo profilo di sviluppatore.
- Le Ruolo finanziario e contabile selezionato nella pagina di registrazione dell'app per la tua candidatura.
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
Nome | Descrizione | Schema | Obbligatorio |
---|---|---|---|
marketplaceId | L'identificativo del marketplace da cui desideri recuperare i metodi di pagamento. Per trovare l'ID del tuo marketplace, consulta ID del Marketplace. | string | Sì |
paymentMethodTypes | Un elenco separato da virgole dei tipi di metodo di pagamento che desideri includere nella risposta. | < corda > matrice | No |
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
Nome | Descrizione | Schema |
---|---|---|
accountHolderName | Il nome del titolare del conto registrato per il metodo di pagamento. | string |
paymentMethodId | L'identificatore del metodo di pagamento. | string |
paymentMethodType | Il tipo di metodo di pagamento. | PaymentMethodType |
tail | Le ultime tre o quattro cifre del metodo di pagamento. | string |
assignmentType | Il 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 |
countryCode | Il 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 |
expiryDate | La 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:
- Autorizzazione del partner di vendita per il quale stai effettuando chiamate. Per ulteriori informazioni, consulta Autorizzazione delle applicazioni Selling Partner API.
- Approvazione per Ruolo finanziario e contabile nel tuo profilo di sviluppatore.
- Le Ruolo finanziario e contabile selezionato nella pagina di registrazione dell'app per la tua candidatura.
Fase 1. Avvia un pagamento
Chiama il initiatePayout
operazione. La richiesta è di tipo InitiatePayoutRequest
e include i seguenti parametri:
Parametri del corpo
Nome | Descrizione | Schema | Obbligatorio |
---|---|---|---|
marketplaceId | Un identificativo del marketplace. Supportato solo nei seguenti marketplace: ES, FR, BE, NL, DE, IT, SE, PL (fare riferimento a ID del marketplace). | string | Sì |
accountType | Il 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 | Sì |
Esempio di richiesta
POST finances/transfers/2024-06-01/payouts/
{
"marketplaceId": "A1PA6795UKMFR9",
"accountType": "Standard Orders"
}
Risposta
Una risposta con esito positivo include quanto segue:
Nome | Descrizione | Schema |
---|---|---|
payoutReferenceId | Un 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.
Errore | Descrizione | Schema |
---|---|---|
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."
}
]
}
Aggiornato 2 mesi fa