Create scheduled payment - V1

PUT

/order/v1/banking/subscriptions/{id}/payments

• Sandbox

  Schedule a payment for an existing subscription.

  

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

Authorizations

• Bearer

Parameters

Path Parameters

id

required

string

The subscription ID (UUID)

Header Parameters

idempotency-key

required

string

Request Body ^required

object

accountId

required

Account ID associated with the scheduled payment

string

Example

133e4567-e89b-12d3-a456-426614174000

dueDate

Due date in ISO 8601 format (YYYY-MM-DD). If not provided, system calculates automatically within cycle and D+2 to D+10 window.

string

Example

2025-02-10

externalId

required

External identifier for the scheduled payment

string

Example

scheduled-payment-12345

amount

required

Payment amount object

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": "199.90"
}

description

Scheduled payment description

string

Example

Monthly subscription charge

purpose

required

Purpose of the scheduled payment.

• FIRST_ATTEMPT: the original charge for the cycle.
• NEW_ATTEMPT_AFTER_DUE_DATE: a further attempt at a charge that was not settled by its due date, such as one canceled for insufficient balance. Accepted only on subscriptions created with allowChargeAfterDueDate. Bacen rules: from the day after the request (dueDate defaults to tomorrow), at most 7 days after the original due date and inside its cycle, on at most 3 dates, one at a time, with the amount of the original charge. It refers to the charge in originalScheduledPaymentId or, when omitted, to the last FIRST_ATTEMPT of the subscription.

string

Allowed values: FIRST_ATTEMPT NEW_ATTEMPT_AFTER_DUE_DATE

Example

FIRST_ATTEMPT

originalScheduledPaymentId

Only for NEW_ATTEMPT_AFTER_DUE_DATE: the scheduled payment to retry (a FIRST_ATTEMPT, or one of its retries). When omitted, the last FIRST_ATTEMPT of the subscription.

string

Example

7c3f2e2a-5b3a-4f7e-9a0a-2e2f9d0c1a2b

webhookUrl

required

Webhook URL to receive status updates

string

Example

https://example.com/webhooks/scheduled-payment

Responses

200

The resource was returned successfully

object

id

required

The unique identifier of the scheduled payment

string

Example

123e4567-e89b-12d3-a456-426614174000

endToEndId

The end-to-end identifier for the payment

string

Example

E1234567820250116150012345ABCDEF

conciliationId

Conciliation ID of the scheduled payment

string

Example

A298FE4B49A1408685311891FC557584

status

required

The status of the scheduled payment

string

Allowed values: INITIAL PENDING ACCEPTED REJECTED COMPLETED ERROR CANCELED CANCELED_INSUFFICIENT_BALANCE

Example

PENDING

dueDate

required

Due date of the scheduled payment

string

Example

2025-02-10

amount

required

Payment amount

object

currency

required

The three-character ISO currency code.

https://en.wikipedia.org/wiki/ISO_4217

string

Allowed values: BRL USD ARS EUR CLP COP MXN PEN BUSD USDT

Example

BRL

value

required

The amount of the transaction, in minor units.

Minor Units Format
------------------

All amount values must be formatted in that currency’s smallest unit.
Two-decimal currency (for example Real): R$ 10,95 BRL, amount will be "10.95".
Two-decimal currency (for example US Dollars): $10.95 USD, amount will be "10.95".
Zero-decimal currency (for example Japanese Yen): ¥1095 JPY, amount will be "1095".
Click here to download the latest official ISO 4217 Currency Table, with Minor Units (number of decimal places) per currency.    

string

Example

10.95

Example

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

description

Scheduled payment description

string

Example

Monthly subscription charge

subscriptionId

required

Subscription ID

string

Example

033bb7f8-f744-418b-852b-c6e2d7afc428

purpose

Purpose of the scheduled payment

string

Example

FIRST_ATTEMPT

externalId

required

External identifier for the scheduled payment

string

Example

scheduled-payment-12345

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

[]