API Reference

OpenFinance - Cash In

This endpoint allows to create a cash in transaction via Payment Initiation with OpenFinance.

Reference Endpoint

  • POST /accounts/payment-initiation

Success Scenario

The request payload is composed of three inner objects: payment, transaction and webhook, as seen in this example request.

{
  "payment": {
    "payer": {
      "taxNumber": "13600642650"
    },
    "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"
  }
}
  • The Request Fields
FieldTypeRequiredDescription
payment.payer.taxNumberstringtrueThe end-user (requestor) CPF.
payment.value.originalstringtrueThe effective value to be paid.
payment.redirectUrlstringtrueThe URL the end-user will be redirected to after he/she completes the transaction.
transaction.orderIdstringfalseA custom order id the integrator might want to provide for counter-check when the response arrives.
transaction.orderDescriptionstringfalseA custom description the integrator might want to provide for counter-check when the response arrives.
webhook.urlstringtrueAn absolute URL to recieve webhook notification events.
webhook.customHeaderNamestringfalseA custom header name for counter-check when the webhook message arrives.
webhook.customHeaderValuestringfalseA custom header value for counter-check when the webhook message arrives.
  • 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
FieldTypeDescription
transactionIdStringAn Unique Identifier (UID) for the transaction.
checkoutUrlStringThe URL where to the merchant should redirect the end-user, so that he/she can proceed with the payment.

📘

CPF Validation

Just like on PIX transactions, PagFast validates the CPF and denies requests for fake CPFs. While integrating, please use one of these real world CPFs for test: 13600642650, 10777438666.

Failure Scenarios (Useful Examples)

Scenario 1: Missing required field 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: Authentication Failure

If a request include an expired or invalid authentication token, the following error will be returned.

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

Scenario 3: Invalid field 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"
    }
  }
}

❗️

Malformed requests

During tests, it is possible that integrators provide some incomplete or malformed request that cause a response an error 500 - Internal Server Error.