Redirect payments (Web Payment Module)

Redirect payments are a type of payment flow where the patron is redirected to perform payment on an external payment provider website.

A redirect payment can be used to pay for all or part of a non-zero value order in OCAPI.

Redirect payment stages

Create redirect payment

Once an order is ready for payment/completion, a redirect payment can be initiated by calling the CreateRedirectPayment endpoint. Note:

• The webPaymentMethodId should correspond to the unique identifier of a configured redirect payment method. If the unique identifier is unknown, use the GetWebPaymentMethods endpoint to load the list of available payment methods for the order. See also Retrieving configured payment methods.
• Set the redirectReturnUrl to the client application's current page so that the payment connector will return to the application after redirecting.
• When creating a redirect payment, the client application should track that a redirect payment has been created to confirm the payment status after redirection. See confirming payment for more information.

{
  "webPaymentMethodId": 0,
  "redirectReturnUrl": "https://example.com"
}

A redirectUrl property linking to the external payment page will be returned, to which the client application should be redirected:

{
  "redirectPayment": {
    "id": "string",
    "type": "Redirect",
    "value": 0.1,
    "status": "Pending"
  },
  "redirectUrl": "https://example.com/VistaWebPay/Request.aspx?token=1e4ca24bf0354578b3c94586683701f9",
  "updatedOrderExpiresAt": "2024-01-31T02:00:17.3979183+00:00"
}

Differences to legacy API flows

In previous API services, the ExternalPaymentStarting endpoint would be used with the following legacy properties:

POST /RESTTicketing.svc/order/startexternalpayment HTTP/1.1

{
  "AutoCompleteOrder": true,
  "OrderCompletionInfo": {
    "CustomerInfo": {
      "Email": "string",
      "Phone": "string",
      "Name": "string",
      "ZipCode": "string",
      "PickupName": "string",
      "OptionalMemberId": "string",
      "CustomerTaxName": "string",
      "CustomerTaxNumber": "string",
      "CustomerTaxAddress": "string"
    },
    "PrintSettings": {
      "GeneratePrintStream": true,
      "PrintTemplateName": "string",
      "PrintStreamType": 0,
      "GenerateConcessionVoucherPrintStream": true,
      "GenerateBookingVoucherPrintStream": true
    },
  }
}

• AutoCompleteOrder - this property is no longer required as orders are always automatically completed after a redirect payment created by the CreateRedirectPayment has been completed.
• OrderCompletionInfo.CustomerInfo - the customer's details must now be set prior to starting a redirect payment via the SetCustomer endpoint.
• OrderCompletionInfo.PrintSettings - print streams must now be requested after order completion via the GetPrintStreams endpoint.

Confirming payment

Once the patron has completed or cancelled the payment at the external site they will be redirected back to the page specified by redirectReturnUrl. The redirectReturnUrl will have a token query parameter automatically appended by the Web Payment Module, i.e., {redirectReturnUrl}?token={token}.

At the same time, the Web Payment Module process will automatically attempt to complete the order in the Digital Platform.

Order completion does not need to be requested by the client application. The client should instead poll:

1. The GetCurrentRedirectPayment endpoint, to confirm the payment has a status of Completed:

{
  "id": "string",
  "type": "Redirect",
  "value": 0.1,
  "status": "Completed"
}

2. The GetOrderCompletion endpoint, to confirm the order completion has a status of Completed:

{
  "orderId": "string",
  "orderType": "Standard",
  "status": "Completed",
  "transactionNumber": 0,
  "updatedOrderExpiresAt": null
}

The client application can then use the GetCompletedOrder endpoint to retrieve the details of the completed order as needed.

Differences to legacy API flows

In previous API services, the GetOrder endpoint would be instead be polled to confirm order completion.

GET /RESTTicketing.svc/order/details?userSessionId={orderId} HTTP/1.1