Subscription qrcode - V1

POST

/order/v1/banking/subscriptions

• Production
• Sandbox

  Request a subscription (PIX Automatico).

  The journey is selected by "type" - see the request examples below:
  - AUTHORIZATION_QRCODE (journey 2): authorization only. Charges are created afterwards through PUT /public/v1/banking/subscriptions/{id}/payments.
  - AUTHORIZATION_QRCODE_IMMEDIATE_PAYMENT (journey 3): composite QR Code that settles a first charge and authorizes the recurrence in a single read. Requires "initialCharge".

  "fixedAmount" and "maxAmountFloor" are both optional and mutually exclusive: send one, or neither.
  The examples list the two so you can see them side by side - drop the one you do not want before
  sending, because a request carrying both is rejected.

  

NOTE: Please, to authenticate use the scope: “api://app-order-prd”

Authorizations

• Bearer

Request Body ^required

object

accountId

required

The receiver account id.

string

Example

8a0df6d3-679c-4942-974d-885eb57cf829

type

required

Type of the subscription QR code.

Glossary:

• AUTHORIZATION_QRCODE: PIX Automático Journey 2. Generates a QR Code containing only the recurring payment authorization data.
• AUTHORIZATION_QRCODE_IMMEDIATE_PAYMENT: PIX Automático Journey 3. Generates a composite QR Code with an immediate payment and recurring payment authorization.

string

Allowed values: AUTHORIZATION_QRCODE AUTHORIZATION_QRCODE_IMMEDIATE_PAYMENT

Example

AUTHORIZATION_QRCODE

allowChargeAfterDueDate

required

Allow charge after due date

boolean

Example

true

allowAdjustToBusinessDay

required

Whether to adjust weekend due dates to the next weekday. Local holidays are not currently handled.

boolean

Example

true

frequencyType

required

Frequency type of the subscription

string

Allowed values: WEEKLY MONTHLY QUARTERLY SEMIANNUAL ANNUAL

Example

MONTHLY

startDate

required

Start date of the subscription in YYYY-MM-DD format. It cannot be earlier than the current date in Brasilia time; today is accepted.

string

Example

2024-07-01

endDate

End date of the subscription in YYYY-MM-DD format

string

Example

2025-07-01

fixedAmount

Fixed amount for the subscription

object

currency

required

Currency code

string

Allowed values: BRL

Example

BRL

value

required

Amount value as a numeric string. A JSON number is also accepted.

string

Example

10.00

maxAmountFloor

Minimum value that the payer may configure as the authorization maximum amount

object

currency

required

Currency code

string

Allowed values: BRL

Example

BRL

value

required

Amount value as a numeric string. A JSON number is also accepted.

string

Example

10.00

debtor

required

Debtor information for the subscription payment

object

document

required

Document of the debtor

object

type

required

Document type

string

Allowed values: CPF CNPJ

Example

CPF

number

required

Document number

string

Example

12345678910

name

required

Name of the debtor

string

Example

John Doe

payer

Payer information used by journeys with an immediate payment, such as AUTHORIZATION_QRCODE_IMMEDIATE_PAYMENT (PIX Automático Journey 3).

object

document

required

Document of the payer

object

type

required

Document type

string

Allowed values: CPF CNPJ

Example

CPF

number

required

Document number

string

Example

12345678910

name

required

Payer name

string

Example

John Doe

initialCharge

Initial charge configuration. Required when type is AUTHORIZATION_QRCODE_IMMEDIATE_PAYMENT (PIX Automático Journey 3).

object

pixKey

required

PIX key used to generate the first payment QR Code

string

Example

[email protected]

amount

required

Amount for the first payment

object

currency

required

Currency code

string

Allowed values: BRL

Example

BRL

value

required

Amount value as a numeric string. A JSON number is also accepted.

string

Example

10.00

Example

{
  "currency": "BRL",
  "value": "10.00"
}

description

Description of the subscription

string

Example

Monthly subscription for service X

webhookUrl

required

Webhook URL for subscription events

string

Example

https://yourdomain.com/subscription-webhook

externalId

required

A unique code representing the subscription QR code on your system

string

Example

ed014d60-3753-4ed8-8349-480f823d4caa

Examples

Journey 2 - authorization only (AUTHORIZATION_QRCODE)

A QR Code that only authorizes the recurrence. Nothing is charged when it is read: the first charge is created later through the scheduled payment endpoint. “fixedAmount” and “maxAmountFloor” are both listed to show the two options: both are optional and only one may be sent, so keep the one you need and drop the other.

{
  "accountId": "f288ae0d-47fd-4207-aee4-0a384888bd96",
  "type": "AUTHORIZATION_QRCODE",
  "externalId": "subscription-2024-0001",
  "description": "Premium plan",
  "webhookUrl": "https://yourdomain.com/subscription-webhook",
  "frequencyType": "MONTHLY",
  "startDate": "2024-07-01",
  "endDate": "2025-07-01",
  "allowChargeAfterDueDate": true,
  "allowAdjustToBusinessDay": true,
  "fixedAmount": {
    "currency": "BRL",
    "value": "49.90"
  },
  "maxAmountFloor": {
    "currency": "BRL",
    "value": "120.00"
  },
  "debtor": {
    "name": "Maria Silva",
    "document": {
      "type": "CPF",
      "number": "52998224725"
    }
  }
}

Journey 3 - authorization + first charge (AUTHORIZATION_QRCODE_IMMEDIATE_PAYMENT)

Same payload as journey 2 plus “initialCharge” (required) and “payer” (optional, and only used by this journey). Reading the QR Code settles the first charge and authorizes the recurrence at once, so the response also carries the immediate payment data. “fixedAmount” and “maxAmountFloor” follow the same rule as in journey 2: both optional, only one may be sent.

{
  "accountId": "f288ae0d-47fd-4207-aee4-0a384888bd96",
  "type": "AUTHORIZATION_QRCODE_IMMEDIATE_PAYMENT",
  "externalId": "subscription-2024-0002",
  "description": "Premium plan",
  "webhookUrl": "https://yourdomain.com/subscription-webhook",
  "frequencyType": "MONTHLY",
  "startDate": "2024-07-01",
  "endDate": "2025-07-01",
  "allowChargeAfterDueDate": true,
  "allowAdjustToBusinessDay": true,
  "fixedAmount": {
    "currency": "BRL",
    "value": "49.90"
  },
  "maxAmountFloor": {
    "currency": "BRL",
    "value": "120.00"
  },
  "debtor": {
    "name": "Maria Silva",
    "document": {
      "type": "CPF",
      "number": "52998224725"
    }
  },
  "payer": {
    "name": "Maria Silva",
    "document": {
      "type": "CPF",
      "number": "52998224725"
    }
  },
  "initialCharge": {
    "pixKey": "[email protected]",
    "amount": {
      "currency": "BRL",
      "value": "49.90"
    }
  }
}

Responses

200

The resource was returned successfully

object

id

required

Subscription identifier

string

Example

e10db0f6-44db-4bfd-8b13-6eb8a2f3b4e3

status

required

Status of the subscription

string

Allowed values: INITIAL PENDING_AUTHORIZATION ACCEPTED REJECTED CANCELED ERROR

Example

PENDING_AUTHORIZATION

qrcodeImageBase64

required

QR code image encoded in base64

string

qrcodeData

required

QR code payload data

string

Example

00020126580014BR.GOV.BCB.PIX0136d2901f4e-4f6e-4e2d-8c8a-5f3c3f00000052040000530398654041.005802BR5925Nome do Recebedor6009Sao Paulo61080540900062070503***6304B14F

initialCharge

Immediate payment details. Available only for journeys that support an initial charge.

object

orderId

Identifier of the order that settles the immediate payment. Use it to follow the charge through the order endpoints and to match the order webhook. Absent only when the subscription failed before the order was created.

string

Example

9c8f1b40-2f2e-4d3a-9b1f-7c1e2a4d5f60

expireDateTime

required

Expiration datetime (ISO)

string

Example

2024-01-01T12:00:00Z

conciliationId

required

Conciliation identifier of the immediate payment.

string

Example

A298FE4B49A1408685311891FC557584

amount

required

Amount of the initial charge

object

currency

required

The currency field.

string

Example

BRL

value

required

The value field.

string

Example

10.95

Example

{
  "currency": "BRL",
  "value": "10.00"
}

providerId

required

The provider identifier

string

Example

RR33630661202512302c950f66b14

externalId

required

The subscription code on partner system

string

Example

b42b91f9-9a72-4cc8-bf57-a337699a5f82

Examples

Journey 2 - authorization only

{
  "id": "1f9a2b6c-6a0e-4a5e-9a1f-6d4f1f6f6b21",
  "status": "PENDING_AUTHORIZATION",
  "qrcodeImageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "qrcodeData": "00020126580014BR.GOV.BCB.PIX0136d2901f4e-4f6e-4e2d-8c8a-5f3c3f00000052040000530398654041.005802BR5925Nome do Recebedor6009Sao Paulo61080540900062070503***6304B14F",
  "providerId": "RR33630661202512302c950f66b14",
  "externalId": "subscription-2024-0001"
}

Journey 3 - authorization + first charge

“initialCharge” is returned only by this journey. Its “conciliationId” identifies the immediate payment, which settles as a regular order and is notified through the order webhook.

{
  "id": "1f9a2b6c-6a0e-4a5e-9a1f-6d4f1f6f6b21",
  "status": "PENDING_AUTHORIZATION",
  "qrcodeImageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "qrcodeData": "00020126580014BR.GOV.BCB.PIX0136d2901f4e-4f6e-4e2d-8c8a-5f3c3f00000052040000530398654041.005802BR5925Nome do Recebedor6009Sao Paulo61080540900062070503***6304B14F",
  "providerId": "RR33630661202512302c950f66b14",
  "externalId": "subscription-2024-0002",
  "initialCharge": {
    "orderId": "9c8f1b40-2f2e-4d3a-9b1f-7c1e2a4d5f60",
    "amount": {
      "currency": "BRL",
      "value": "49.90"
    },
    "conciliationId": "A298FE4B49A1408685311891FC557584",
    "expireDateTime": "2024-07-02T12:00:00Z"
  }
}

400

object

error

string

Example

INVALID_REQUEST

message

string

details

Array<object>

object

field

string

issue

string

description

string

Example

[
  {
    "field": "field_name",
    "issue": "INVALID",
    "description": "Field is invalid"
  }
]

401

Unauthorized Request

object

error

string

Example

UNAUTHORIZED

message

string

Example

Unauthorized Request

details

Array<object>

object

field

string

issue

string

description

string

Example

[]

403

object

error

string

Example

FORBIDDEN_ERROR

message

string

details

Array<object>

object

field

string

issue

string

description

string

Example

[]

404

Resource not found

object

error

string

Example

NOT_FOUND

message

string

Example

Resource not found

details

Array<object>

object

field

string

issue

string

description

string

Example

[]

500

object

error

string

Example

INTERNAL_ERROR

message

string

details

Array<object>

object

field

string

issue

string

description

string

Example

[]