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:
- Autorização do parceiro de vendas para quem você está fazendo chamadas. Para obter mais informações, consulte Como autorizar aplicativos da API do parceiro de vendas.
- Aprovação para o Função financeira e contábil no seu perfil de desenvolvedor.
- O Função financeira e contábil selecionado na página de registro do aplicativo para seu aplicativo.
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
Nome | Descrição | Schema | Obrigatório |
---|---|---|---|
marketplaceId | O identificador do mercado do qual você deseja recuperar as formas de pagamento. Para encontrar a ID do seu mercado, consulte IDs de mercado. | string | Sim |
paymentMethodTypes | Uma lista separada por vírgulas dos tipos de formas de pagamento que você deseja incluir na resposta. | < fio > matriz | Nã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
Nome | Descrição | Schema |
---|---|---|
accountHolderName | O nome do titular da conta que está registrado na forma de pagamento. | string |
paymentMethodId | O identificador da forma de pagamento. | string |
paymentMethodType | O tipo de método de pagamento. | PaymentMethodType |
tail | Os últimos três ou quatro dígitos da forma de pagamento. | string |
assignmentType | O 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 |
countryCode | O 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 |
expiryDate | A 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:
- Autorização do parceiro de vendas para quem você está fazendo chamadas. Para obter mais informações, consulte Como autorizar aplicativos da API do parceiro de vendas.
- Aprovação para o Função financeira e contábil no seu perfil de desenvolvedor.
- O Função financeira e contábil selecionado na página de registro do aplicativo para seu aplicativo.
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
Nome | Descrição | Schema | Obrigatório |
---|---|---|---|
marketplaceId | Um identificador de mercado. Suportado somente nos seguintes mercados: ES, FR, BE, NL, DE, IT, SE, PL (consulte IDs de mercado). | string | Sim |
accountType | O 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 . | string | Sim |
Exemplo de solicitação
POST finances/transfers/2024-06-01/payouts/
{
"marketplaceId": "A1PA6795UKMFR9",
"accountType": "Standard Orders"
}
Resposta
Uma resposta bem-sucedida inclui o seguinte:
Nome | Descrição | Schema |
---|---|---|
payoutReferenceId | Um 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.
Erro | Descrição | Schema |
---|---|---|
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."
}
]
}
Atualizado há 2 meses