Cancelling a payment

In this guide, we will initiate a cancellation on a payment, and validate it if necessary.

Depending on the type of payment and whether the connector allows it or not, it may be possible to cancel a payment through our API once it has been validated and confirmed, before it has been executed.

This guide assumes you are cancelling a payment respecting the following criteria:

• The state of the payment is either created or pending.

• If the state of the payment is pending, the execution date type of all instructions in the payment is not instant.

Note that this guide assumes you have the following information on hand:

• A Powens domain with Pay enabled.

• A Powens domain client with client identifiers, thereafter named clientId and clientSecret.

• A URL to redirect the end user to at the end of the process, registered with the client, thereafter named redirectURL.

• An optional state that will be transmitted to your redirect URL, thereafter named optionalRedirectState.

• A payment you wish to cancel, for which the identifier will be represented as paymentId.

Initiate the cancellation

You first need to request the cancellation from our API, by doing the following request:

POST /payments/{paymentId}

{
  "cancel": true,
  "client_redirect_uri": "{redirectURL}",
  "client_state": "{optionalRedirectState}"
} 

From here, you can obtain multiple responses corresponding to multiple scenarios:

Cancellation successful

If the cancellation could successfully be done without any validation by the end user, the response looks like the following:

{
  "id": {paymentId},
  "state": "rejected",
  "error_code": "cancelledByUser",
  ...
}

End user validation required

Some cancellations require a validation by the end user. In this case, the response looks like the following:

{
  "id": {paymentId},
  "state": "pending",
  "state_detail": "cancelling_webauth",
  ...
}

Cancellation is not supported

If the connector doesn't support cancelling the provided payment, the following response will be received:

{
    "code": "notSupported",
    "description": "Bad request, please check your request parameters.",
    ...
}

Validate a payment cancellation if necessary

If the cancellation requires validation from the end user, we need to build a URL and redirect our end user to it.

Obtain the payment cancellation validation token

In order for the payer to be able to validate the payment cancellation, you first need to create a token scoped to validate the created payment specifically. This is done exactly the same way as for when you want to obtain a token for validating the payment:

POST /payments/{paymentId}/scopedtoken
Authorization: Bearer {accessToken}

{
  "scope": ["payments:validate"]
}

{
  "token": "{scopedAccessToken}",
  "scope": "payments:validate",
  "expires_in": 604800,
  "id_payment": {paymentId}
}

See the POST /payments/{id}/scopedtoken endpoint reference for more information.

Build the payment validation URL

Now that you have the payment validation token, you can create the webview URL by taking the webview URL and adding the following parameters to it:

• client_id: the client identifier for your application (clientId).

• redirect_uri: the same redirect URL you've used when creating the payment (redirectURL).

• state: the same state you've used when creating the payment (optionalRedirectState).

• code: The scoped token you've generated on your previous request to the API.

• payment_id: the identifier of the payment.

This will make you obtain an URL of the form:

https://{domain}.biapi.pro/2.0/auth/webview/{lang}/payment?client_id={clientId}&redirect_uri={redirectURL}&state={optionalRedirectState}&code={scopedAccessToken}&payment_id={paymentId}

You can redirect your payer to this URL.

Receive a callback from the payer

Once the payer has either completed the payment validation flow, or has cancelled from either our Webview or the bank's interface, they will go on the callback URL you have configured on the payment with the following parameters:

• state: the optional client state you have configured on the payment, i.e. {optionalClientState}.

• id_payment: the identifier of the payment that the user comes from.

• error (optional): set to "cancelled" if the payer has cancelled the payment cancellation validation from our Webview; in this case, the cancellation is still ongoing.

• error_code (optional): set to the payment's error code, if the payment has been cancelled or rejected by the bank.

• bank_message (optional): set to the bank message, if available.

• payment_state (optional): the state of the payment, if the payer comes from the bank's interface.

For security reasons, it is recommended to check the payment's state manually; see Get the payment status.

If the payment still has the pending state and the cancelling_webauth state detail, you must send the payer back to the Webview by following instructions from Obtain the Payment Validation Token onwards.