API Reference

PIX - Cash Out

Este endpoint permite a criação de uma requisição de cash out PIX

Endpoint de Referência

  • POST /accounts/pix/cashout

Cenário de Sucesso

O payload da request é composto por três objetos internos: payment, transaction e webhook, conforme visto neste exemplo de payload de request.

{
  "payment": {
    "recipient": {
      "name": "CHRISTINE IGNACIO",
      "cpf": "14435549603"
    },
    "key": {
      "type": "CPF",
      "value": "14435549603"
    }, 
    "value": "10.50"
  },
  "transaction": {
    "orderId": "in-01901847474-560183477261001736",
    "orderDescription": "Created via postman"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjMGQtODI1My"
  }
}
  • Os Campos da Request
CampoTipoObrigatórioDescrição
payment.recipient.namestringtrueO nome do usuário final (destinatário)
payment.recipient.cpfstringtrueO usuário final (destinatário) GLOSSÁRIO:CPF
payment.key.typestringtrueUm dos tipos de chave PIX válidos, como CPF, EMAIL, PHONE ou EVP (Chave Gerada Aleatoriamente)
payment.key.valuestringtrueO valor da chave
payment.valuestringtrueO valor efetivo a pagar
transaction.orderIdstringtrueUm id de pedido customizado que o integrador pode querer fornecer para contraverificação quando a resposta chegar
transaction.orderDescriptionstringfalseUma descrição customizada que o integrador pode querer fornecer para contraverificação quando a resposta chegar
webhook.urlstringtrueUm GLOSSÁRIO:ABSOLUTE URL para receber eventos de notificação de webhook
webhook.customHeaderNamestringfalseUm nome de cabeçalho personalizado para contraverificação quando a mensagem do webhook chega
webhook.customHeaderValuestringfalseUm valor de cabeçalho personalizado para contra-verificação quando a mensagem do webhook chega

Na solicitação de exemplo, observe que o valor do CPF (14435549603) aparece duas vezes. A primeira identifica a chave PIX para onde o pagamento será transferido e a outra identifica o usuário final proprietário da conta, o recebedor.

  • Success Response (201 - Created)
{
  "statusCode": "Done",
  "data": {
    "transaction": {
      "id": "95c0f371-bc71-4c06-823e-74cf5bc308fa",
      "orderId": "in-1409184409-98758761847691",
      "date": "2023-07-29T11:09:21.851Z",
      "state": "Created",
      "amount": "10.50"
    }
  }
}
  • The Response Fields
FieldTypeDescription
transaction.idStringUm identificador exclusivo (UID)
transaction.orderIdStringUm ID fornecido pelo integrador na solicitação de transação para contraverificação
transaction.dateStringA data de criação do pedido de transação
transaction.stateStringO estado inicial da transação. Ele começa como Created, o que significa que a transação ainda será cadastrada em um Banco Adquirente.
transaction.amountStringO valor original da transação.

📘

Validação de CPF

A PayBrokers valida o CPF e nega pedidos de CPFs falsos. Durante a integração, use um destes CPFs do mundo real para teste: 13600642650, 10777438666.

Cenários de Falha (Exemplos Úteis)

Cenário 1: Faltando campo requerido payment.value.

{
  "payment": {
    "recipient": {
      "name": "CHRISTINE IGNACIO",
      "cpf": "14435549603"
    },
    "key": {
      "type": "CPF",
      "value": "14435549603"
    }
  },
  "transaction": {
    "orderId": "in-1409184409-98758761847691",
    "orderDescription": "Created via postman"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjMGQtODI1My"
  }
}
  • Resposta de Falha (400 - Bad Request)
{
  "statusCode": "Error",
  "error": {
    "name": "InvalidRequestFormatError",
    "message": "The request body is invalid. See error object `details` property for more info",
    "details": [
      {
        "path": "/payment",
        "code": "required",
        "message": "must have required property 'value'",
        "info": {
          "missingProperty": "value"
        }
      }
    ]
  }
}

Cenário 2: Valor inválido para payment.key.type (e-mail).

{
  "payment": {
    "key": {
      "type": "e-mail",
      "value": "[email protected]"
    },
    "value": "10"
  },
  "transaction": {
    "orderId": "in-1409184409-98758761847691",
    "orderDescription": "Created via postman"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjMGQtODI1My"
  }
}
  • Resposta de Falha (400 - Bad Request)
{
  "statusCode": "Error",
  "error": {
    "name": "InvalidRequestFormatError",
    "message": "The request body is invalid. See error object `details` property for more info",
    "details": [
      {
        "path": "/payment/key/type",
        "code": "enum",
        "message": "must be equal to one of the allowed values",
        "info": {
          "allowedValues": [
            "CPF",
            "EMAIL",
            "PHONE",
            "EVP"
          ]
        }
      }
    ]
  }
}

Cenário 3: Falha de Autenticação

Se uma solicitação incluir um token de autenticação expirado ou inválido, o seguinte erro será retornado.

  • Resposta de Falha (401 Unauthorized)
{
  "statusCode": "Error",
  "error": {
    "name": "AuthenticationError",
    "message": "The authorization token is invalid",
    "details": {
      "reason": "AuthenticationTokenInvalid"
    }
  }
}

Cenário 4: Faltando campo requerido payment.key.type

{
  "payment": {
    "recipient": {
      "name": "CHRISTINE IGNACIO",
      "cpf": "14435549603"
    },
    "key": {
      "value": "14435549603"
    }, 
    "value": "10.53"
  },
  "transaction": {
    "orderId": "in-1409184409-98758761847691",
    "orderDescription": "Created via postman"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjMGQtODI1My"
  }
}
  • Resposta de Falha (409 - Conflict)
{
  "statusCode": "Error",
  "error": {
    "name": "OperationError",
    "code": "OperationError",
    "details": {
      "reason": "PixKeyTypeNotAllowed",
      "message": "This operation is not available for the PIX key of type 'undefined'"
    }
  }
}

❗️

Requests Malformadas

Durante os testes, é possível que os integradores forneçam alguma requisição incompleta ou malformada que gere como resposta um erro 500 - Internal Server Error.