Flow

The following steps will guide you through completing a refund:

1. Request a PIS dedicated access token
2. Trigger the refund providing the session_id of the original payment
3. Verify the payment on callback such that the payment status and order ID matches
4. Listen to Webhook to intercept payments status change events as a redundant channel to the redirect callback

🚧 Important

Signature, digest, date and x-request-id headers are optional in SANDBOX environment but mandatory when calling the PRODUCTION one.

💡 Note

By default, a refund will initiate a PIS payment from your bank account directly to the bank account of the PSU. This requires an SCA to be done with your bank account for each refund. Alternatively, refunds can be done from a Fintecture Account which reduces the friction from SCA and enable mass-refunds to help with your daily operations.

Fintecture Accounts can be created directly from the Console.

IMPORTANT NOTICE

• Refunds operated on an external beneficiary bank account will create an "reverse" PIS requiring you to authenticate and validate by SCA the refund from your banks payment initiation web interface.
• Refunds operated on an acquiring beneficiary bank account are processed immediately using

Refund types

• Partial refunds are enabled by overriding the refund amount attribute. It is also possible to change the communication field by overriding the communication attribute.
• Multi-refunds are possible by triggering several times the refund API. Each call will trigger a new refund session until the total refund amount exceeds the original amount at which point the API will return an error.
• Cancelled refunds are not considered in the total refund amount.

1. Request an Access Token

The first step is to authenticate your application with the Fintecture API Gateway and this is done using the /access token API, as illustrated.

To use the API, you must first create a basic token. To do so, encode the following string using a base64 encoder:

`basic_token` = base64(`app_id`:`app_secret`)

Include your app_id and basic_token the the following request:

POST /oauth/accesstoken HTTP/1.1
Authorization: Basic [basic_token]
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&app_id=[app_id]&scope=PIS

The expected response is the following:

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJub25lIn0.eyJleHAiOjE1MTQwODA0MjQsI...",
  "expires_in": 3600
}

Store the access_token for the next step.

2. Create a Refund

The second step is to create a refund on the payment session providing the session_id of the original payment.

Simply POST the illustrated request including all the necessary headers, body and query string. For more information on each field, see the Refund API.

POST /pis/v2/refund HTTP/1.1
Authorization: Bearer [access_token]
Signature: [signature]
Digest: [digest]
Date: [date]
x-request-id: [request_id]
Accept: application/json
Content-Type: application/json

{
  "meta": {
    "session_id": "ecec9f13407f4c2cb5f1591255e8f815"
  },
  "data": {
    "attributes": {
      "amount": "149.3"
    }
  }
}

The response will include a session_id from which you can verify it's status in the next section.

As you can see, the amount field was specified in order to override the original payment amount. By overriding it, you can specify a number equal or lower to the original account in order to operate a partial refund.

Additional functionalities are:

• overriding the communication field to introduce a custom label to your refund
• overriding the debtor bank account id to refund from another account than the one you collected on
• overriding the scheme to refund on your chosen payment scheme (for EUR payments, INSTANT SEPA is the default scheme)

3. Verify the refund status

Fetch the status of the refund using the (GET payments/:id API)[] and confirm when the payment reaches a final status.

GET pis/v2/payments/[session_id] HTTP/1.1
Accept: application/json
Authorization: Bearer [access_token]
Signature: [signature]
Date: [date]
X-Request-Id: [x-request-id]