O recurso Transferência (Transfer) possibilita a movimentação de saldo entre contas PagSeguro.
Através desta API é possível realizar uma movimentação de saldo entre contas PagSeguro.
Para solicitar a transferência, é necessário ter o e-mail ou o account-id da conta destino.
O tempo médio para efetivação de uma transferência é de 1 minuto. Porém, em alguns casos excepcionais, essa efetivação pode chegar a um tempo máximo de 24 horas.
| Ambiente | URL |
|---|---|
| Sandbox | https://secure.sandbox.api.pagseguro.com |
| Produção | https://secure.api.pagseguro.com |
Autenticação
Todas as APIs públicas do PagSeguro requerem autenticação. Através dessa, identificamos e autorizamos o integrador a utilizar nossas APIs e seus recursos, bem como eventuais configurações adicionais.
As chaves de acesso são confidenciais e recomendamos não compartilhá-las em ambientes públicos ou com terceiros.
Ambiente de Sandbox:
1º passo: Criar uma conta no nosso ambiente de Sandbox
Para criar uma conta no ambiente de Sandbox utilize este link
2º passo: Gerar um Certificado Digital mTLS
Para gerar seu certificado digital, utilize a API de Certificado Digital
O certificado digital mTLS precisará ser gerado toda vez que o certificado atual expirar ou com a frequência que o integrador julgar necessária. Quando um novo certificado é gerado, o antigo não será mais válido. A validade do Certificado Digital é de 2 anos.
Atenção
Para dar continuidade ao processo é necessário que você tenha esse certificado digital. Qualquer alteração no fluxo desse passo a passo acarretará em um retorno de erro.
3º passo: Criar suas credenciais (Client ID e Client Secret)
Para requisitar seu token do connect você deve obter seu Client_id e Client_secret seguindo o descrito na documentação Criar uma aplicação
4º passo: Gerar chave da conta digital web (token do connect)
Para gerar um token no Connect com escopo de criação e consulta de transferências, você deve acessar esse link
5º passo: Solicitar uma transferência
Clique aqui para acessar a documentação para criação de um POST.
6º passo: Consultar uma transferência solicitada
Existem duas formas para que você consiga consultar as transferências que solicitou:
- Consultar transferências via ID do Cliente ou período de data
- Consultar uma transferência via ID PagSeguro
7º passo: Solicitar homologação e inclusão na allowlist do ambiente de Produção
Para solicitar homologação e inclusão na lista de permissão siga esse link
Ambiente de Produção:
1º passo: Para se integrar no ambiente produtivo é necessário que o 7º passo para integração ao ambiente de sandbox esteja concluído.
2º passo: Gerar um Certificado Digital mTLS
Para gerar seu certificado digital, utilize a API de Certificado Digital
O certificado digital mTLS precisará ser gerado toda vez que o certificado atual expirar ou com a frequência que o integrador julgar necessária. Quando um novo certificado é gerado, o antigo não será mais válido. A validade do Certificado Digital é de 2 anos.
Atenção
Para dar continuidade ao processo é necessário que você tenha esse certificado digital. Qualquer alteração no fluxo desse passo a passo acarretará em um retorno de erro.
3º passo: Criar suas credenciais (Client ID e Client Secret)
Para requisitar token do connect você deve obter seu Client_id e Client_secret seguindo o descrito na documentação Criar uma aplicação
4º passo: Gerar chave da conta digital web (token do connect)
Para gerar um token no Connect com escopo de criação e consulta de transferências, você deve acessar esse link
5º passo: Solicitar uma transferência
Clique aqui para acessar a documentação para criação de um POST.
6º passo: Consultar uma transferência solicitada
Existem duas formas para que você consiga consultar as transferências que solicitou:
- Consultar transferências via ID do Cliente ou período de data
- Consultar uma transferência via ID PagSeguro
Autenticação
Para garantir a segurança de sua transação, realizaremos a conferência do certificado informado com a chave da conta digital web do cliente. Caso não sejam referentes ao mesmo cliente, a transação não será efetivada e retornaremos o erro 403.
Transações e seus Status
A Máquina de Estado é composta pelos seguintes status:
- CREATED: Enviado syncronicamente na resposta da criação da transferência. Indica que a solicitação foi recebida com sucesso;
- PROCESSING: Indica que a transação está em andamento;
- SUCCESS: Indica que a transação foi concluída com sucesso;
- FAILED: Indica que a solicitação foi reprovada pela Pagseguro ou não foi autorizada pelo requisitante ou teve o tempo de autorização ultrapassado.
Tabela de erros
| Parâmetro | Error | Descrição |
|---|---|---|
| amount | invalid_amount | Invalid amount format |
| amount | parameter_required_missing | Field can not be null. |
| amount.value | parameter_required_empty | Field can not be null. |
| amount.value | amount_too_large | Enter only characters smaller than 20.000.000,00 |
| amount.value | invalid_amount | Enter only numeric characters greater than zero |
| amount.currency | invalid_currency | Use a valid value: BRL. Only capital letters. |
| amount.currency | parameter_required_empty | Field can not be null. |
| description | invalid_string_max_length | Field must have a minimum of 1 and a maximum of 72 characters. |
| reference_id | invalid_string_max_length | Field must have a minimum of 1 and a maximum of 64 characters. |
| instrument | parameter_required_missing | Field can not be null. |
| instrument.type | parameter_required_empty | Field can not be null. |
| instrument.type | transfer_invalid_type | Use a valid value: P2P. |
| instrument.p2p | transfer_required_object_p2p | Field can not be null. |
| instrument.p2p.email | account_not_exists | Destination account does not exist |
| instrument.p2p.account_id | account_not_exists | Destination account does not exist |
| instrument.p2p.account_id | parameter_required_missing | "Enter a value for the destination account: ""email"" or ""account_id""" |
| instrument.p2p.email | account_divergent | Account_id value and email value do not represent the same account |
| instrument.p2p.email | invalid_email | Invalid email format |
| x-idempotency-key | idempotency_key_in_use | Transfer already exists |
| notification_urls | invalid_notification_url | Invalid notification url format |
| invalid_payload_format | Invalid JSON format | |
| instrument.p2p.email | account_inactive | Destination account is inactive |
| instrument.p2p.account_id | account_inactive | Destination account is inactive |
| instrument.p2p.account_id | invalid_id | Invalid account_id format |
| notification_urls | invalid_notification_url | Only one URL is accepted. |
| x-idempotency-key | invalid_string_max_length | IdempotencyKey must have at maximum 200 characters and cannot have special characters. |
| x-idempotency-key | invalid_string_max_length | IdempotencyKey must have at maximum 200 characters and cannot have special characters. |
| - | account_blocked | Destination account is blocked |
| - | transfer_insufficient_balance | Insufficient balance to transfer |
| - | failed | Transfer failed |
| - | transfer_security_rejected | Transfer rejected for security reasons. Contact us for more information. |
| start_date | invalid_date | Enter a valid value for the start_date |
| end_date | invalid_date | Enter a valid value for the end_date |
| - | invalid_date_period | Enter a valid date period. The end date must be equal to or greater than the start date, and neither date can be in the future |
| start_date | invalid_date_format | Enter a valid date format: yyyy-MM-dd |
| end_date | invalid_date_format | Enter a valid date format: yyyy-MM-dd |
| page | invalid_page | Enter a valid values for page |
| size | invalid_size | Enter a valid values for size |
Cenários Sandbox
| Cenário | parameter | error | description |
|---|---|---|---|
| Cenário de Sucesso: envie o amount.value terminando diferente de 10, 11, 12 e 13 | success | ||
| Cenário de e-mail inexistente: utilize o e-mail [email protected] | instrument.p2p.email | account_not_exists | Destination account does not exist |
| Cenário de account id inexistente: utilize o account_id: ACCO_000 | instrument.p2p.account_id | account_not_exists | Destination account does not exist |
| Cenário de contas distintas: envie o email [email protected] e account_id: ACCO_001 | instrument.p2p.email | account_divergent | Account_id value and email value do not represent the same account |
| Cenário de falha: Envie o amount.value terminado em 11 | failed | Transfer failed | |
| Cenário de conta bloqueada com e-mail: Envie o email: [email protected] e informe um amount.value que termine com 12 | account_blocked | Destination account is blocked | |
| Cenário de conta bloqueada com account_id: Envie o account_id: ACCO_001 e informe um amount.value que termine com 13 | account_blocked | Destination account is blocked | |
| Saldo insuficiente: Envie um amount.value terminando em 10 | transfer_insufficient_balance | Insufficient balance to transfer |