Guia de casos de uso da API de transferências v2024-06-01

Como recuperar formas de pagamento e iniciar pagamentos usando a API Transfers.

Versão da API: v2020-07-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.

O que é a API de transferências?

Os vendedores podem usar o API de transferências v2024-06-01 para recuperar informações sobre os métodos de pagamento associados a um vendedor e iniciar pagamentos para o método de depósito do vendedor registrado.

Tutorial 1: Recuperar detalhes da forma de pagamento associados a um vendedor

Este tutorial demonstra como recuperar a lista de formas de pagamento adicionadas pelo vendedor em um determinado mercado.

Pré-requisitos

Para concluir este tutorial com sucesso, você deve ter:

Etapa 1. Obtenha detalhes das formas de pagamento associadas a um vendedor em um determinado mercado

Chame a operação getPaymentMethods com os seguintes parâmetros:

Parâmetros de consulta

NomeDescriçãoSchemaObrigatório
marketplaceIdO identificador do mercado do qual você deseja recuperar as formas de pagamento. Para encontrar a ID do seu mercado, consulte IDs de mercado.stringSim
paymentMethodTypesUma lista separada por vírgulas dos tipos de formas de pagamento que você deseja incluir na resposta.< fio > matrizNão
Exemplos de solicitações
GET /finances/transfers/2024-06-01/paymentMethods?marketplaceId=ATVPDKIKX0DER GET /finances/transfers/2024-06-01/paymentMethods?marketplaceId=ATVPDKIKX0DER?paymentMethodTypes=BANK_ACCOUNT,CARD
Resposta
NomeDescriçãoSchema
accountHolderNameO nome do titular da conta que está registrado na forma de pagamento.string
paymentMethodIdO identificador da forma de pagamento.string
paymentMethodTypeO tipo de método de pagamento.PaymentMethodType
tailOs últimos três ou quatro dígitos da forma de pagamento.string
assignmentTypeO tipo de método de pagamento padrão. Este campo é igual a DEFAULT_DEPOSIT_METHOD se o método de pagamento for o método de depósito padrão.AssignmentType
countryCodeO código do país de duas letras em ISO 3166-1 alfa-2 formato. Para métodos de pagamento no CARD categoria, o código é para o país onde o cartão foi emitido. Para métodos de pagamento no BANK_ACCOUNT categoria, o código é do país em que a conta está localizada.string
expiryDateA data de validade de um cartão usado para pagamentos.ExpiryDate
Exemplo de resposta
{ "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: Iniciar um pagamento

Este tutorial demonstra como iniciar um pagamento pelo método de depósito do vendedor. Somente um pagamento sob demanda pode ser iniciado para cada mercado e tipo de conta em um período de 24 horas.

Pré-requisitos

Para concluir este tutorial com sucesso, você deve ter:

Etapa 1. Iniciar um pagamento

Ligue para o initiatePayout operação. A solicitação é do tipo InitiatePayoutRequest e inclui os seguintes parâmetros:

Parâmetros do corpo

NomeDescriçãoSchemaObrigatório
marketplaceIdUm identificador de mercado. Suportado somente nos seguintes mercados: ES, FR, BE, NL, DE, IT, SE, PL (consulte IDs de mercado).stringSim
accountTypeO tipo de conta no mercado selecionado para o qual um pagamento deve ser iniciado. Para os mercados compatíveis da UE, o único tipo de conta é Standard Orders.stringSim

Exemplo de solicitação

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

Resposta

Uma resposta bem-sucedida inclui o seguinte:

NomeDescriçãoSchema
payoutReferenceIdUm resultado bem-sucedido de início de pagamento inclui um payoutReferenceId que podem ser usados pelos parceiros de vendas para rastrear as informações de pagamento. É o ID do grupo de eventos financeiros para um pagamento iniciado.string

Exemplo de resposta

{ "payoutReferenceId": "3DM7DQi8DPAMOLOSaN5HxT0q2waNwH95fopx3XXXXxx" }

Resposta de erro

Uma resposta malsucedida inclui uma lista de erros descrevendo os motivos pelos quais um pagamento não foi iniciado.

ErroDescriçãoSchema
code
required
Um código de erro que identifica o tipo de erro que ocorreu.
Exemplo: "InvalidInput"
string
message
required
Uma mensagem que descreve a condição de erro em um formato legível por humanos.
Exemplo: "The input request had one or more invalid input parameters."
string
details
optional
Detalhes adicionais que podem ajudar o chamador a entender ou corrigir o problema.
Exemplo: "The following input parameters are invalid : [marketplaceId]."
string

Exemplo de resposta de erro:

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

Esta página ajudou você?