Initiating a bulk payment with the Webview
In this guide, we will create and validate a "bulk" payment using the Pay product.
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
andclientSecret
.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
.
Bulk payments are payments with multiple instructions to be executed once by the bank. They are equivalent to initiating multiple one-time payments, except that there is only one connector and one validation for all of the instructions.
Akin to one-time payments, the instructions of a bulk payment can have different types:
"First open day" payments: classic payments usually executed within a few business days (SEPA Credit Transfers, GB BACS, GB CHAPS, GB Faster Payments, ...).
"Instant" payments: payments usually executed within a few minutes (SEPA Instant Credit Transfers).
"Deferred" payments: classic payments only executed at a provided future date.
Currently, all instructions of a given payment must have the same type, and for deferred bulk payments, all instructions must be executed on the same day.
The basic initiation workflow is the same as in Initiating a one-time payment with the Webview, with the following notable differences:
The payment object contains two or more instructions.
The payment status needs to be interpreted differently.
The basic initiation workflow will be the following:
Obtain a token suitable for creating bulk payments
In order to create bulk payments, we need a special access token with the payments:admin
scope, obtained using client credentials:
See Service Tokens for more information.
Create a bulk payment
You can now create a bulk payment request with the following request:
A payer_identity
for the bulk payment request and a beneficiary_identity
for every instruction is required and must contain information on either the payer (which you redirect to the webview) or the beneficiary (matching the routing information). For the definition of such objects, see the Identity object definition.
The following are examples of different identity kinds with Pay:
See the POST /payments
endpoint reference and the PaymentInitRequest
object description for more information on the payload or returned information.
Obtain the bulk payment validation token
In order for the payer to be able to validate the bulk payment request, you first need to create a token scoped to validate the created bulk payment specifically. You can do this using the token created in Obtain a token suitable for creating payments:
See the POST /payments/{id}/scopedtoken
endpoint reference for more information.
Build the bulk payment validation URL
Now that you have the bulk payment validation token, you can create the webview URL by taking the webview URL and adding the following parameters to it:
domain
: your client domain.client_id
: the client identifier for your application (clientId
).redirect_uri
: the same redirect URL you've used when creating the bulk payment (redirectURL
).state
: the same state you've used when creating the bulk payment (optionalRedirectState
).code
: The scoped token you've generated on your previous request to the API.payment_id
: the identifier of the bulk payment.
This will make you obtain a URL of the form:
You can redirect your payer to this URL.
Receive a callback from the payer
Once the payer has either completed the bulk 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 bulk payment, i.e.{optionalClientState}
.id_payment
: the identifier of the bulk payment that the user comes from.error
(optional): set to "cancelled
" if the payer has cancelled the bulk payment from our Webview.error_code
(optional): set to the bulk 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 bulk payment, if the payer has been redirected by the bank.
For security reasons, following such a callback from the payer, it is recommended to check the bulk payment's state manually; see Get the bulk payment status.
Check on a bulk payment's state
During and after the initiation of a bulk payment, you may want to check on the status of said bulk payment, or to get data back from the bulk payment initiation request.
Receive bulk payment updated events using webhooks (recommended method)
In order to receive updates when a bulk payment switches states, it is recommended to set up the Payment Updated webhook and wait for events regarding bulk payments.
Webhook events will only be triggered during a background refresh/synchronization of the bulk payment's state.
Webhook events will not be emitted if only an instruction changes states, only if the payment changes states, i.e. if all instructions reach a final state.
For more information, see Webhooks in the Payments API reference.
Get the bulk payment status
This method is not recommended for polling the bulk payment's status regularly, it is recommended to wait for incoming webhook events to this end.
However, it is recommended for when receiving a callback regarding a bulk payment from an end user, or for debugging purposes.
In order to get a given bulk payment's status, you can call the GET /payments/{id}
endpoint, with the identifier of the bulk payment. See API endpoints for more information.
Process the bulk payment statuses
In the resulting bulk payment resource, you are to get both the state
property of the payment, and if it is available, the state
property of every of its instructions. At instruction-level, if the status is not null
, you can conclude the following:
If the status is
pending
, the instruction is still awaiting execution.If the status is
rejected
, the instruction has been rejected by either the bank, or the end user through the bank.If the status is
accepted
, the bank will not provide further updates past the initiation for this instruction; if you accept the risks, you can consider this instruction as executed.If the status is
done
, the instruction has been executed by the bank.
The bulk payment's state property signifies, at a higher level, of the status of its instructions:
If the bulk payment's state is
pending
, at least one instruction is still awaiting execution. You probably still want to check the instructions' statuses to find out if some instructions have changed state.If the bulk payment's state is
rejected
, all instructions are considered to have therejected
status.If the bulk payment's state is
accepted
, all instructions are considered to have theaccepted
status.If the bulk payment's state is
done
, all instructions are considered to have thedone
status.If the bulk payment's state is
partial
, at least one instruction is eitherdone
oraccepted
, and at least one instruction is considered to have therejected
status.
In the case the bank reports a partial
status with no detail regarding the state of the instructions, the payment will be reported having the partial
status, and all of its instructions will have the accepted
status.
See the Payment object definition for reference.
Last updated