Pagamentos Criar pagamento

Criar Pagamento

Este endpoint permite a criação de um pagamento, possibilitando a inclusão de todas as informações necessárias. Certifique-se de adicionar corretamente os detalhes do pagamento e as informações do cliente.

Criando o link de pagamento

Para criar um link de pagamento via API, basta enviar uma requisição POST para a rota /v2/payments. Em resposta, você receberá o callback_return_url da transação.

Método de pagamento

Por momento todos os pagamentos estão por padrão no tipo pix.

DOCUMENTO DO COMPRADOR

Caso você não envie o payer document usaremos o documento de cadastro da sua conta de vendedor para gerar o pagamento!

URL de retorono

Você pode passar o parâmentro [PAYMENT] para reescrever o mesmo com o PAYMENT ID.

EXEMPLO: https://seusite.com/retorno/[PAYMENT]

Pagamento sem Split

Exemplo abaixo tem a finalidade de gerar uma cobraça sem split.

POST /v2/payments

Requer autorização para o escopo: payments.post

Parâmetros de requisição

HEADER

~~Authorization~~ Bearer obrigatório

Token de autorização gerado a partir do APP_ID e APP_TOKEN.

BODY

~~item~~ object obrigatório

Este objeto representa os dados básicos do pagamento.

~~amount~~ float obrigatório

Valor da transação.

~~description~~ string obrigatório

Descrição referente a transação.

~~payer~~ object obrigatório

Este objeto representa os dados do pagador.

~~name~~ string obrigatório

Valor da transação.

~~email~~ string obrigatório

E-mail do pagador.

~~document~~ string

CPF ou CNPJ do pagador.

~~fone~~ string

Celular do pagador.

~~callback~~ object

Este objeto representa as informações de retorno do pagamento.

~~webhook_url~~ string

URL para receber o evento POST de webhook.

~~return_url~~ string

URL redirecionar o pagador para o seu site.

~~reference_id~~ (int)

ID de referência do seu sistema.

~~custom_id~~ (int)

ID de referência do seu produto.

PD9waHAKJEFjY2Vzc1Rva2VuID0gJ3tBQ0NFU1NfVE9LRU59JzsKJGhlYWRlcnMgPSBhcnJheSgKCSdBdXRob3JpemF0aW9uOiBCZWFyZXIgJy4kQWNjZXNzVG9rZW4sCgknQ29udGVudC1UeXBlOiBhcHBsaWNhdGlvbi9qc29uJywKKTsKCiRkYXRhID0gKHNtbUFycmF5UEhQKTsKCiRjaCA9IGN1cmxfaW5pdCgpOwpjdXJsX3NldG9wdCgkY2gsIENVUkxPUFRfVVJMLCAne0FQSV9VUkx9L3YyL3BheW1lbnRzJyk7CmN1cmxfc2V0b3B0KCRjaCwgQ1VSTE9QVF9IVFRQSEVBREVSLCAkaGVhZGVycyk7CmN1cmxfc2V0b3B0KCRjaCwgQ1VSTE9QVF9SRVRVUk5UUkFOU0ZFUiwgVFJVRSk7CmN1cmxfc2V0b3B0KCRjaCwgQ1VSTE9QVF9DVVNUT01SRVFVRVNUICwgJ1BPU1QnKTsKY3VybF9zZXRvcHQoJGNoLCBDVVJMT1BUX1BPU1QgLCB0cnVlKTsKY3VybF9zZXRvcHQoJGNoLCBDVVJMT1BUX1BPU1RGSUVMRFMgLCAkZGF0YSk7CmN1cmxfc2V0b3B0KCRjaCwgQ1VSTE9QVF9TU0xfVkVSSUZZUEVFUiwgRkFMU0UpOwokcmVzcG9uc2UgPSBjdXJsX2V4ZWMoJGNoKTsJCmN1cmxfY2xvc2UoJGNoKTsKCmVjaG8gJHJlc3BvbnNlOwo/Pg==

Pagamento com Split

Exemplo abaixo tem a finalidade de executar uma cobraça com split.

POST /v2/payments

Requer autorização para o escopo: payments.post

Parâmetros de requisição

HEADER

~~Authorization~~ Bearer obrigatório

Token de autorização gerado a partir do APP_ID e APP_TOKEN.

BODY

~~item~~ object obrigatório

Este objeto representa os dados básicos do pagamento.

~~amount~~ float obrigatório

Valor da transação.

~~description~~ string obrigatório

Descrição referente a transação.

~~payer~~ object obrigatório

Este objeto representa os dados do pagador.

~~name~~ string obrigatório

Valor da transação.

~~email~~ string obrigatório

E-mail do pagador.

~~document~~ string

CPF ou CNPJ do pagador.

~~fone~~ string

Celular do pagador.

~~callback~~ object

Este objeto representa as informações de retorno do pagamento.

~~webhook_url~~ string

URL para receber o evento POST de webhook.

~~return_url~~ string

URL redirecionar o pagador para o seu site.

~~reference_id~~ (int)

ID de referência do seu sistema.

~~custom_id~~ (int)

ID de referência do seu produto.

~~split~~ object

Para redirecionar parte da transação para outra conta de forma automática e instantânea você precisa adicionar o objeto split junto ao "payload" ao executar a cobrança do Gift Card.

~~username~~ string obrigatório

Usuário que irá receber porcentagem referente a transação.

~~percentage~~ int obrigatório

Porcentagem que o usuário acima receberá (max: 50).

PD9waHAKJEFjY2Vzc1Rva2VuID0gJ3tBQ0NFU1NfVE9LRU59JzsKJGhlYWRlcnMgPSBhcnJheSgKCSdBdXRob3JpemF0aW9uOiBCZWFyZXIgJy4kQWNjZXNzVG9rZW4sCgknQ29udGVudC1UeXBlOiBhcHBsaWNhdGlvbi9qc29uJywKKTsKCiRkYXRhID0gKHNtbUFycmF5UEhQKTsKCiRjaCA9IGN1cmxfaW5pdCgpOwpjdXJsX3NldG9wdCgkY2gsIENVUkxPUFRfVVJMLCAne0FQSV9VUkx9L3YyL3BheW1lbnRzJyk7CmN1cmxfc2V0b3B0KCRjaCwgQ1VSTE9QVF9IVFRQSEVBREVSLCAkaGVhZGVycyk7CmN1cmxfc2V0b3B0KCRjaCwgQ1VSTE9QVF9SRVRVUk5UUkFOU0ZFUiwgVFJVRSk7CmN1cmxfc2V0b3B0KCRjaCwgQ1VSTE9QVF9DVVNUT01SRVFVRVNUICwgJ1BPU1QnKTsKY3VybF9zZXRvcHQoJGNoLCBDVVJMT1BUX1BPU1QgLCB0cnVlKTsKY3VybF9zZXRvcHQoJGNoLCBDVVJMT1BUX1BPU1RGSUVMRFMgLCAkZGF0YSk7CmN1cmxfc2V0b3B0KCRjaCwgQ1VSTE9QVF9TU0xfVkVSSUZZUEVFUiwgRkFMU0UpOwokcmVzcG9uc2UgPSBjdXJsX2V4ZWMoJGNoKTsJCmN1cmxfY2xvc2UoJGNoKTsKCmVjaG8gJHJlc3BvbnNlOwo/Pg==

Respostas possíveis

201 400 403 400

/* Esse exemplo de resposta ocorre quando a cobrança foi gerada com sucesso! */
{
  "access": "granted",
  "payments": {
    "id": "TRR-00000000000000000000",
    "intent": "sale",
    "state": "pending",
    "payment_url": "https://payment.i9giftcard.com/payment/TRR-00000000000000000000",
    "amount": "77.39",
    "payment_method": "pix",
    "callback_reference_id": null,
    "callback_return_url": "https://seusite.com/?token=TRR-00000000000000000000",
    "create_time": "2025-04-18 07:14:46"
  }
}

/* Esse exemplo de resposta ocorre quando você informou o campo BODY com parâmetros incorretos*/
{
  "access": "bad-request",
  "payments": {
    "error": "valor do produto não identificado",
    "error_code": 72,
    "error_status": 400
  }
}

/* Esse exemplo de resposta ocorre quando o app não tem permissão para gerar pagamentos! */
{
  "access": "forbidden",
  "giftcards": {
    "error": "App sem permissão para usar este endpoint",
    "error_code": 70,
    "error_status": 400
  }
}

/* Esse exemplo de resposta ocorre quando o documento do pagador está incorreto! */
{
  "access": "bad-request",
  "giftcards": {
    "error": "CPF do pagador está incorreto! utilize o formato ###.###.###-##",
    "error_code": 78,
    "error_status": 400
  }
}

A tabela abaixo descreve os atributos presentes no JSON retornado.

access

Retorna granted informado sobre o sucesso da solicitação.

payments Sem resultados retorna um objeto vazio.

id ID do pagamento atual para buscar o resultado se foi pago ou não. string
intent Tipo de intenção. string
state Estado do pagamento. string
payment_url Link para o comprador efetuar a venda. string
amount Valor atual do pagamento. float
payment_method Método do pagamento. string
callback_reference_id ID de referência que foi passado na criação do pagamento. string
callback_return_url Endereço que o pagador vai ser redirecionado após o pagamento. string
create_time Data e hora que o pagamento foi gerado. date_time

Última atualização em 26 de dez. de 2024