Preauthorization Flow

The preauthorization flow allows Billwerk+ Transform users to secure payment means before processing actual charges. This is particularly useful for confirming that funds are available and that payment methods are valid before proceeding with a transaction.

Initiating Preauthorization

To initiate a preauthorization, clients should use the /api/Preauth endpoint with the necessary payment details.

Common Use Case

In the common case, the Customer initiates the signup flow and sends initial data to plarform.
Then, Billwerk+ Transform processes this data and requests the Integrator to initiate the signup process by creating a new Preauth. As a result of this response, the platform expects Preauth with specific PSP data (transaction identifier from the PSP side, status, expired date of Preauth etc.). During this process, the Integrator stores Preauth data and shares it with Billwerk+ Transfrom.

Request

POST /api/Preauth
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "pspSettingsId": "{psp_settings_id}",
  "transactionId": "{transaction_id}",
  "requestedAmount": 100.00,
  "currency": "EUR",
  "paymentMeansReference": {
    "role": "CreditCard",
    "successReturnUrl": "https://yourdomain.com/success",
    "errorReturnUrl": "https://yourdomain.com/error",
    "abortReturnUrl": "https://yourdomain.com/abort"
  },
  "payerData": {
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "[email protected]",
    "language": "EN"
  }
}

Response

Upon successful initiation, the response will indicate that the preauthorization has been accepted and is pending completion.

{
  "status": "Pending",
  "preauthTransactionId": "20221108-636bd596c10cfc318b1bfabb",
  "message": "Preauthorization initiated successfully."
}

Redirect Use Case

This approach supports a more intricate signup scenario, where customers are redirected to the PSP checkout page as outlined in the scheme above. Here’s a detailed description of the process:

• Field Inclusion: The request from Billwerk to the Integrator will include a {SuccessUrl} field. This URL is crucial as it serves as the finalization URL that should be provided by the Integrator to the PSP.
• Providing {CheckoutUrl}: In response, the Integrator must provide a {CheckoutUrl} within the Preauth response model. Billwerk uses this URL to redirect the customer to the PSP checkout page.
• Redirection to Finalization Page: After submitting payment data, customers are redirected to the finalization page using the {SuccessUrl}.
• Fetching Preauth State: Billwerk completes the signup process by fetching the Preauth state from the Integrator. This step ensures that all transaction details are verified and the signup process is concluded successfully.

This scenario ensures a seamless transition between the customer’s initiation of the signup to the final verification of the transaction by Billwerk, involving crucial redirects and data submissions to secure and finalize the signup process.

Preauthorization Cancellation Flow

Billwerk+ Transfrom can use the /Cancel endpoint if a preauthorization needs to be cancelled.

Request

To cancel a preauthorization, provide the unique transaction ID received during the preauthorization phase.

POST /api/Preauth/{preauthTransactionId}/Cancel
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "transactionId": "20221108-636bd596c10cfc318b1bfabb"
}

Response

The response will confirm whether the cancellation was successful or not.

{
  "status": "Cancelled",
  "message": "Preauthorization cancelled successfully."
}

Handling Errors

Both initiating and cancelling preauthorizations can result in errors, such as invalid payment data or connection issues. Ensure your integration handles these by following the Error Handling guidelines outlined in this documentation.