Endpoint used to retrieve the details of a specific Automatic Pix payment instruction.

The instruction represents the execution process of an automatic payment related to a recurring charge. Through this retrieval, the integration can track the current status of the instruction, identify the linked authorization, locate the related charge, and check whether there was a refusal in the processing.

When to use

Use this endpoint when your integration needs to retrieve a specific Automatic Pix payment instruction.

Some common scenarios include:

• tracking the processing of an automatic charge;
• validating whether an instruction was scheduled, completed, canceled, or refused;
• investigating automatic payment failures;
• retrieving the refusal reason of an instruction;
• relating an instruction to the corresponding Automatic Pix authorization;
• relating an instruction to the linked charge;
• updating the internal status of a recurring charge in the source system;
• complementing the handling of events received by Webhook.

When not to use

Do not use this endpoint to:

• create a new payment instruction;
• create an Automatic Pix authorization;
• cancel an authorization;
• create a recurring charge;
• change a linked charge;
• attempt to execute a refused instruction again;
• replace the use of Webhooks in asynchronous flows.

If you need to create a recurring charge with Automatic Pix, use the charge creation endpoint informing the corresponding authorization.

Required permission

To use this endpoint, the API key must have read permission for Automatic Pix:

PIX_AUTOMATIC:READ

If the key used does not have permission for this operation, the request may return an authorization error.

Request parameter

This endpoint uses only the payment instruction identifier in the request path.

Identifier example:

cbfdf6ef-9bd8-48ba-b8cd-efd61a9f614c

The id must correspond to an existing payment instruction in the authenticated Asaas account.

This endpoint does not require sending parameters in the request body.

Payment instruction dependencies

An Automatic Pix payment instruction is related to other resources in the recurring flow.

Before using this retrieval, consider that:

• there must be an Automatic Pix authorization linked to the instruction;
• the authorization must be related to the payer who granted consent;
• the recurring charge must have been created with a link to the authorization;
• the instruction is sent for processing according to the linked charge;
• the paymentId field allows the instruction to be related to the corresponding charge;
• the authorization.id field allows the instruction to be related to the corresponding authorization.

Recommended flow

In a typical integration, retrieving a payment instruction is part of the following flow:

Create Automatic Pix authorization
↓
Customer makes the initial payment and authorizes the recurrence
↓
Authorization becomes ACTIVE
↓
Integration creates a recurring charge linked to the authorization
↓
Asaas generates the payment instruction
↓
Payer bank processes the instruction
↓
Integration tracks events by Webhook
↓
Integration retrieves the specific instruction, when necessary

Request example

curl --request GET \
  --url https://api-sandbox.asaas.com/v3/pix/automatic/paymentInstructions/cbfdf6ef-9bd8-48ba-b8cd-efd61a9f614c \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Response example

In case of success, the API returns the payment instruction details.

{
  "id": "d1c9c4b2-6a97-4573-9d6d-26bb64f04c28",
  "endToEndIdentifier": "E00416968202111161635q5bk0brYk2C",
  "authorization": {
    "id": "35363f6e-93e2-11ec-b9d9-96f4053b1bd4",
    "endToEndIdentifier": "RR1234567820240115abcdefghijk",
    "customerId": "cus_000005735721"
  },
  "dueDate": "2020-01-31",
  "status": "SCHEDULED",
  "paymentId": "pay_tsp88gie3b5e6o2p",
  "refusalReason": null
}

Returned information

When retrieving a payment instruction, it is possible to check information such as:

Payment instruction status

The status field indicates the current state of the payment instruction.

The main returned statuses are:

How to interpret the statuses

The interpretation of the status should guide the integration’s next action.

Refusal reasons

When the instruction returns the REFUSED status, the refusalReason field may indicate the refusal reason.

Some examples of refusal reasons include:

Important behaviors

When using this endpoint, consider the following behaviors:

• the retrieval returns only the data of a specific instruction;
• the endpoint does not change the state of the instruction;
• the endpoint does not create new charges;
• the endpoint does not reprocess refused instructions;
• the endpoint does not replace tracking by Webhooks;
• the paymentId field must be used to retrieve the linked charge;
• the authorization.id field must be used to retrieve the linked authorization;
• a refused instruction must be handled according to the reason returned in refusalReason;
• if there is any doubt about the charge state, also retrieve the linked payment through paymentId.

Important business rules

Before implementing this endpoint, consider the following rules:

• the payment instruction must exist in Asaas;
• the informed id must belong to the authenticated account;
• the request must be authenticated with a valid API Key;
• the API Key must have the PIX_AUTOMATIC:READ permission;
• the instruction must be linked to an Automatic Pix authorization;
• the instruction must be linked to a recurring charge;
• the linked authorization must be monitored throughout its entire lifecycle;
• Automatic Pix recurring charges must be created by the integration;
• the payment instruction must respect the operational creation window defined for Automatic Pix;
• status changes should preferably be tracked by Webhooks.

Operational impacts

Retrieving a payment instruction can directly impact how your integration updates recurring charges.

Some important impacts:

• a DONE instruction may indicate that the automatic payment flow advanced successfully;
• a REFUSED instruction may require communication with the customer, a new attempt, or the end of the cycle, according to the refusal reason;
• a CANCELLED instruction may indicate that that cycle should no longer be charged automatically;
• a SCHEDULED instruction should not yet be treated as a completed payment;
• inconsistencies between status, paymentId, and internal records may generate reconciliation divergences;
• relying only on periodic retrievals may delay the application status update.

For this reason, combine Webhooks with occasional retrievals to keep the integration synchronized.

Common errors

Some common errors when using this endpoint include:

Best practices

For a safer implementation, it is recommended to:

• store the payment instruction id when it is returned by the API or by Webhook;
• also store the authorization.id and the paymentId;
• use Webhooks to track status changes;
• retrieve this endpoint when you need to confirm the current state of a specific instruction;
• handle REFUSED based on the refusalReason field;
• not consider SCHEDULED as a completed payment;
• not automatically reprocess refused instructions without evaluating the reason;
• retrieve the linked charge through paymentId when there is a divergence;
• retrieve the linked authorization when there is suspicion of cancellation, expiration, or status change;
• respond to Webhooks idempotently and avoid duplication in the source system;
• test success, cancellation, and refusal scenarios in Sandbox before operating in Production.

Sandbox precautions

This endpoint can be used in Sandbox to validate the monitoring of Automatic Pix payment instructions.

During testing, it is recommended to validate:

• retrieval of an existing instruction;
• retrieval with an invalid id;
• retrieval without adequate permission;
• GET call with an empty body;
• correlation between authorization.id, paymentId, and internal records;
• handling of SCHEDULED, DONE, CANCELLED, and REFUSED statuses;
• handling of refusalReason when there is a refusal;
• update of the source system after Webhook events.

These tests help ensure that your integration correctly tracks the lifecycle of recurring charges via Automatic Pix.

Related content

See also:

• Automatic Pix;
• Automatic Pix implementation;
• Create Automatic Pix authorization;
• List authorizations;
• Retrieve a single authorization;
• Create charge with Automatic Pix;
• List payment instructions;
• Refusal reasons;
• Automatic Pix Webhook flows;
• Automatic Pix FAQ.