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": "ISADORA STEPHANY",
      "cpf": "13600642650"
    },
    "key": {
      "type": "CPF",
      "value": "13600642650"
    }, 
    "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
CampoTipoRequiredDescrição
payment.recipient.namestringtrueO nome do usuário final (recebedor)
payment.recipient.cpfstringtrueO CPF do usuário final (recebedor)
payment.key.typestringtrueUm dos tipos de chave PIX válidos, como CPF, E-mail, Telefone ou Chave Gerada Aleatoriamente
payment.key.valuestringtrueO valor da chave
payment.valuestringtrueO valor efetivo a ser pago
transaction.orderIdstringfalseUm id customizado que o integrador pode querer fornecer para contraverificação quando a resposta é recebida.
transaction.orderDescriptionstringfalseUma descrição customizada que o integrador pode querer fornecer para contraverificação quando a resposta é recebida.
webhook.urlstringtrueUma URL absoluta para receber as notificações de eventos 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 contraverificação quando a mensagem do webhook chega

Na solicitação de exemplo, observe que o valor do CPF (13600642650) 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.

Tipos de chave PIX podem ser validados baseado em sua estrutura, como segue:

Tipo ChaveDescriçãoPadrão RegexExemplo
CNPJO CNPJ é o identificador único de empresas brasileiras.^[0-9]{14}$46261360000148
CPFO CPF é o identificador único de indivíduos brasileiros.^[0-9]{11}$04368535405
PHONEUm telefone válido^\+[1-9]\d{1,14}$+5583986182244
EMAILUm e-mail válido"^[a-z0-9.!#$&'*+/=?^_`{[email protected]
EVPUm tipo de chave PIX gerado usando a biblioteca OpenSSL EVP.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}b6295ee1-f054-47d1-9e90-ee57b74f60d9
  • 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
CampoTipoDescrição
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

O PagFast 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": "ISADORA STEPHANY",
      "cpf": "13600642650"
    },
    "key": {
      "type": "CPF",
      "value": "13600642650"
    }
  },
  "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": "ISADORA STEPHANY",
      "cpf": "13600642650"
    },
    "key": {
      "value": "13600642650"
    }, 
    "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.