# 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

```mermaid
flowchart TB
    A(Create redirect payment) --> B
    B(Client application redirects to external payment page) --> C
    C(Patron completes or cancels payment) --> D
    D(Client application confirms payment status) --> E
    E(Client application confirms order completion status)
```

## Create redirect payment

Once an order is ready for payment/completion, a redirect payment can be initiated by calling the [CreateRedirectPayment](/openapi/digital-platform/openapi/payments/ocapiorderpayments_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](/openapi/digital-platform/openapi/payments/ocapiwebpaymentmethods_getwebpaymentmethods) endpoint to load the list of available payment methods for the order. See also [Retrieving configured payment methods](/digital-platform/payments#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](#confirming-payment) for more information.


```json
{
  "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:

```json
{
  "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:

```http
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](/openapi/digital-platform/openapi/payments/ocapiorderpayments_createredirectpayment) has been completed.
- `OrderCompletionInfo.CustomerInfo` - the customer's details must now be set prior to starting a redirect payment via the [SetCustomer](/openapi/digital-platform/openapi/orders/ocapiordercustomer_setcustomer) endpoint.
- `OrderCompletionInfo.PrintSettings` - print streams must now be requested after order completion via the [GetPrintStreams](/openapi/digital-platform/openapi/completed-orders/ocapicompletedorders_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](/openapi/digital-platform/openapi/payments/ocapiorderpayments_getcurrentredirectpayment) endpoint, to confirm the payment has a `status` of `Completed`:


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

1. The [GetOrderCompletion](/openapi/digital-platform/openapi/completion/ocapiordercompletion_getordercompletion) endpoint, to confirm the order completion has a `status` of `Completed`:


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

The client application can then use the [GetCompletedOrder](https://developer.vista.co/openapi/digital-platform/openapi/completed-orders/ocapicompletedorders_getcompletedorder/) endpoint to retrieve the details of the completed order as needed.

IMPORTANT
For statuses indicating a failed state, the client application should implement appropriate [error handling](/digital-platform/payments/error-handling).

### Differences to legacy API flows

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

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