API Reference

PIX - Cash In

This endpoint allows the creation of a PIX cash in request, with a set of dynamic attributes

Reference Endpoint

  • POST /accounts/pix/cashin

This endpoint allows you to create cash-in transactions. We offer some variations of interest to partners:

  1. Complete Request: involves providing all data, making them mandatory, such as the requester and the amount.
  2. Anonymous Payer: allows the requester's data to be omitted, this way, any payer will be accepted for the transaction.
  3. Editable Value: allows you to configure whether the amount to be paid can be defined by the end user, or whether the defined amount needs to be paid exclusively.

Success Scenarios

Scenario 1: Full Request

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

{
  "payment": {
    "payer": {
      "name": "CHRISTINE IGNACIO",
      "cpf": "13600642650"
    },
    "value": {
      "original": "50",
      "editable": false
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • The Request Fields
FieldTypeRequiredDescription
payment.payerobjectfalseAn optional object that defines the payment requestor data. If not specified the generated QRCode can be paid by any individual.
payment.payer.cpfstringtrueIf the payer object is provided, this field contains the end-user (requestor) CPF.
payment.payer.namestringfalseIf the payer object is provided, this field contains the end-user (requestor) name.
paymentobjecttrueAn object that defines the payment value data.
payment.value.originalstringtrueThis is the standard value to be paid.
payment.value.editablebooleanfalseThis is the flag that specifies if the user can pay a value other than the standard value or not.
transactionobjectfalseAn optional object that describes client-side parameters for counter-check. This information is included both in the response object and the webhook messages.
transaction.orderIdstringtrueA custom order id the integrator should provide for idempotency and counter-check when the response arrives.
transaction.orderDescriptionstringtrueA custom description the integrator might want to provide for counter-check when the response arrives.
webhookobjecttrueA mandatory object that includes the client webhook configurations.
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": {
        "transaction": {
            "id": "625a913f-ac58-499a-8f91-4917aa8fedda",
            "orderId": "in-1414870875-158709817091784",
            "date": "2023-10-27T01:59:01.023Z",
            "state": "Registered",
            "amount": "50"
        },
        "payment": {
            "qrCode": "77914780075295699696br.gov.bcb.pix2564qrcode.sandbox.pagfast.com.br/QR/cob/488968451850629566092063417102430176450477573197289273442834Pagfast Cobranca e Servic6014Campina Grande10484911785727998087***1DFA8C33",
            "qrCodeLocation": "https://api.sandbox.pagfast.com/v1/system/qrcodeviewer/625a913f-ac58-499a-8f91-4917aa8fedda"
        }
    }
}
  • The Response Fields
FieldTypeDescription
transaction.idStringAn Unique Identifier (UID)
transaction.orderIdStringAn ID provided by the integrator in the transaction request for counter-validation
transaction.dateStringThe transaction request creation date
transaction.stateStringThe transaction initial state. It starts as Registered, which means it is already registered in a bank and is waiting for the payment.
transaction.amountStringThe transaction value. A number in float format with up to 6 decimal digits, such as 15.000000
payment.qrCodeStringA code tailored for PIX Copy and Paste feature on bank apps, facilitating the seamless execution of the payment.
payment.qrCodeLocationStringThe URL for a base64 string of graphical QR Code to be scanned using PIX bank apps, enabling the payment's initiation.

📘

CPF Validation

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

Scenario 2: Anonymous payer

{
  "payment": {
    "value": {
      "original": "50"
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Success Response (201 - Created)
{
    "statusCode": "Done",
    "data": {
        "transaction": {
            "id": "9947b80a-8107-4264-938d-56a7f43593f5",
            "orderId": "in-1414870875-158709817091784",
            "date": "2023-10-27T01:58:14.573Z",
            "state": "Registered",
            "amount": "50"
        },
        "payment": {
            "qrCode": "76616684937466847221br.gov.bcb.pix2564qrcode.sandbox.pagfast.com.br/QR/cob/504920436013785957047772193456164644706748877985089166204308Pagfast Cobranca e Servic6014Campina Grande78445932284303602542***BA5BD701",
            "qrCodeLocation": "https://api.sandbox.pagfast.com/v1/system/qrcodeviewer/9947b80a-8107-4264-938d-56a7f43593f5"
        }
    }
}

Scenario 3: Anonymous Payer and Dynamic value

{
  "payment": {
    "value": {
      "original": "50",
      "editable": true      
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Success Response (201 - Created)
{
    "statusCode": "Done",
    "data": {
        "transaction": {
            "id": "44651c37-bd75-4832-97a4-2405196f5948",
            "orderId": "in-1414870875-158709817091784",
            "date": "2023-10-27T01:56:29.600Z",
            "state": "Registered",
            "amount": "50"
        },
        "payment": {
            "qrCode": "94981488354773156916br.gov.bcb.pix2564qrcode.sandbox.pagfast.com.br/QR/cob/303326304022161823741588521546295317587826825487260932178025Pagfast Cobranca e Servic6014Campina Grande24732189570858379466***710B8AEA",
            "qrCodeLocation": "https://api.sandbox.pagfast.com/v1/system/qrcodeviewer/44651c37-bd75-4832-97a4-2405196f5948"
        }
    }
}

🚧

About Dynamic Information

If you are using the anonymous payer, or defined the value as editable, please notice that you must update these information in your system by using the webhook event messages.

Failure Scenarios (Useful Examples)

Scenario 1: Malformed payer. Empty required field (payment.payer)

{
  "payment": {
    "payer": {
    },
    "value": {
      "original": "50"
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • 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/payer",
        "code": "required",
        "message": "must have required property 'cpf'",
        "info": {
          "missingProperty": "cpf"
        }
      }
    ]
  }
}

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: Restricted payment.payer.cpf on banks.

{
  "payment": {
    "payer": {
	    "cpf": "50194184190"
    },
    "value": {
	    "original": "50"
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Failure Response (409 - Conflict)
{
  "statusCode": "Error",
  "error": {
    "name": "OperationError",
    "code": "OperationError",
    "details": {
      "reason": "CounterpartyTaxNumberInvalid",
      "message": "TaxNumber:50194184190"
    }
  }
}

Scenario 4: Invalid real-world payment.payer.cpf.

{
  "payment": {
    "payer": {
	    "cpf": "96449033070"
    },
    "value": {
	    "original": "50"
    }
  },
  "transaction": {
    "orderId": "in-1414870875-158709817091784",
    "orderDescription": "This is a test order."
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTR"
  }
}
  • Failure Response (409 - Conflict)
{
  "statusCode": "Error",
  "error": {
    "name": "OperationError",
    "code": "OperationError",
    "details": {
      "reason": "CounterpartyServiceError",
      "message": "TaxNumber:96449033070"
    }
  }
}

❗️

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.