API Reference

OpenFinance - Cash In

Este endpoint permite criar uma transação de Iniciação de Pagamento via OpenFinance.

Endpoint de Referência

  • POST /accounts/payment-initiation

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": {
    "payer": {
      "taxNumber": "14435549603"
    },
    "value": {
      "original": "10.00"
    },
    "redirectUrl": "https://merchantwebsite.com/success"
  },
  "transaction": {
    "orderId": "in-410987401-001479147149841",
    "orderDescription": "Test-transaction with payment initiation"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjM"
  }
}
  • Os Campos da Request
CampoTipoRequiredDescrição
payment.payer.taxNumberstringtrueO CPF do usuário final (requisitante).
payment.value.originalstringtrueO valor efetivo a ser pago.
payment.redirectUrlstringtrueA URL para a qual o usuário final será redirecionado após completar a transação.
transaction.orderIdstringfalseUma orderId customizada fornecida pelo integrador, caso queira fazer uma contraverificação quando a resposta é recebida.
transaction.orderDescriptionstringfalseUma descrição customizada fornecida pelo integrador, caso queira fazer uma contraverificação quando a resposta é recebida.
webhook.urlstringtrueUma URL absoluta para receber eventos de notificação webhook.
webhook.customHeaderNamestringfalseUm nome de cabeçalho personalizado para contraverificação quando a mensagem do webhook é recebida.
webhook.customHeaderValuestringfalseUm valor associado ao cabeçalho para contraverificação quando a mensagem de webhook é recebida.
  • Success Response (201 - Created)
{
  "statusCode": "Done",
  "data": {
    "transactionId": "0a3d2b84-87ef-4c2e-aa3d-b7cfb6d76e9d",
    "checkoutUrl": "https://checkout.sandbox.pagfast.com/v1/system/checkout/init/0ea70001-0f58-44a2-80ad-953633ff2cc7/0a3d2b84-87ef-4c2e-aa3d-b7cfb6d76e9d"
  }
}
  • The Response Fields
CampoTipoDescrição
transactionIdStringUm identificador exclusivo (UID) para a transação.
checkoutUrlStringA URL para a qual o usuário deve ser redirecionado para que seja possível proceder com o pagamento.

📘

Validação de CPF

Assim como nas transações PIX, a 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": {
    "payer": {
      "taxNumber": "13600642650"
    },
    "redirectUrl": "https://merchantwebsite.com/success"
  },
  "transaction": {
    "orderId": "in-410987401-001479147149841",
    "orderDescription": "Test-transaction with payment initiation"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjM"
  }
}
  • Failure Response (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"
        }
      }
    ]
  }
}

Scenario 2: 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 3: Campo inválido payment.payer.taxNumber

{
    "payment": {
        "value": {
            "original": "10.00"
        },
        "payer": {
            "taxNumber": "33251500012"
        },
        "redirectUrl": "https://merchantwebsite.com/success"
    },
    "transaction": {
        "orderId": "in-410987401-001479147149841",
        "orderDescription": "Test-transaction with payment initiation"
    },
    "webhook": {
        "url": "https://postman-echo.com/post?test=1",
        "customHeaderName": "Authorization",
        "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjM"
    }
}
  • Failure Response (409 - Conflict)
{
  "statusCode": "Error",
  "error": {
    "name": "OperationError",
    "code": "OperationError",
    "details": {
      "reason": "CounterpartyTaxNumberInvalid",
      "message": "TaxNumber:33251500012"
    }
  }
}

❗️

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.