Scenario simulation

This page describes how to simulate the creation and cancellation of payment instrument entries to test the transaction flow with postpaid cards. These simulations are useful for homologation and integration testing.

Information

These requests simulate external transactions and return the HTTP status with the key of the created or canceled entry.

1 - Payment instrument entry creation simulation

Simulates the creation of a payment instrument entry (transaction), such as a purchase or withdrawal made with the postpaid card. The entry will be automatically linked to invoice items according to the installment configuration.

ENDPOINT

/mock/invoice/payment_instrument/POSTPAID_CARD_KEY/payment_instrument_entry

METHOD

POST

Path Parameters

Field	Type	Description	Characters
postpaid_card_key *	string	Unique key of the postpaid card in UUID v4 format	36

Request Body

{
    "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
    "payment_instrument_entry_amount": 100.50,
    "number_of_installments": 3,
    "installment_amount": 33.50,
    "payment_instrument_entry_type": "purchase",
    "payment_instrument_entry_data": {
        "merchant_name": "Test Merchant",
        "merchant_country": "BR",
        "merchant_postal_code": "01310-100",
        "merchant_city": "São Paulo",
        "merchant_street": "Av. Paulista"
    }
}

Request Body Object

Field	Type	Description	Max Char.
request_control_key *	uuidv4	Unique identification key for the request used by the client	36
payment_instrument_entry_amount *	float	Total transaction amount	-
number_of_installments *	integer	Number of transaction installments	-
installment_amount *	float	Amount of each installment	-
payment_instrument_entry_type *	string	Type of payment instrument entry	payment_instrument_entry_type Enumerators
payment_instrument_entry_data *	object	Additional transaction data	payment_instrument_entry_data Object

payment_instrument_entry_type Enumerators

Enumerator	Description
purchase	Purchase made with the card
withdraw	Withdrawal made with the card
postpaid_card_issuance	Postpaid card issuance

payment_instrument_entry_data Object

Field	Type	Description	Characters
merchant_name *	string	Merchant name	-
merchant_country *	string	Merchant country	-
merchant_postal_code *	string	Merchant postal code	-
merchant_city *	string	Merchant city	-
merchant_street *	string	Merchant street	-

Response

STATUS

201

Response Body

{
    "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6"
}

Response Body Params

Field	Type	Description	Characters
payment_instrument_entry_key *	uuidv4	Unique identification key of the created entry in UUID v4 format	36

Behavior

• The simulation creates a payment instrument entry with active status
• The entry will be automatically linked to invoice items according to the number of installments informed
• Invoice items will be organized into invoices according to the wallet closing configuration
• The payment instrument and wallet limits will be validated before allowing entry creation

2 - Payment instrument entry cancellation simulation

Simulates the cancellation of an existing payment instrument entry, changing its status to canceled and releasing the used limit.

ENDPOINT

/mock/invoice/payment_instrument/POSTPAID_CARD_KEY/payment_instrument_entry/REQUEST_CONTROL_KEY/cancel

METHOD

PATCH

Path Parameters

Field	Type	Description	Characters
postpaid_card_key *	string	Unique key of the postpaid card in UUID v4 format	36
request_control_key *	uuidv4	Unique identification key of the original request used in entry creation	36

Request Body

{
    "payment_instrument_entry_amount": 100.50
}

Request Body Object

Field	Type	Description	Max Char.
payment_instrument_entry_amount *	float	Cancellation amount.	-

Response

STATUS

200

Response Body

{
    "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6"
}

Response Body Params

Field	Type	Description	Characters
payment_instrument_entry_key *	uuidv4	Unique identification key of the canceled entry in UUID v4 format	36

Behavior

• Open invoices: Cancellations in open invoices release the limit immediately and remove the amount from the invoice
• Closed invoices: Cancellations in closed invoices create chargebacks that will appear in the invoice_payments_chargebacks field when used in the next invoice