Worldpay (VAP) - Card

Worldpay (VAP) is a payment gateway providing secure card processing solutions primarily for merchants in North America. Worldpay (VAP) offers comprehensive payment processing capabilities with extensive currency support.

Setup

Contact your Worldpay (VAP) account manager to obtain your credentials and set up your account.

Connector configuration

After setting up your Worldpay (VAP) account, you can configure the connector in Gr4vy using one of the following methods:

Flow - Configure payment routing rules through your Gr4vy dashboard
API integration - Specify the payment_service_id when creating transactions to explicitly route payments to this connector

Credentials

Configure the following credentials in the Gr4vy dashboard, which are obtained from your Worldpay (VAP) account manager:

Username - Your Worldpay (VAP) username for API access
Password - Your Worldpay (VAP) password for authentication
Merchant ID - Your Worldpay (VAP) merchant identifier
Default Report Group - The default report group value used for every Worldpay (VAP) API request. See the Worldpay (VAP) docs for more information on how report groups work
Use sandbox (optional) - When enabled in the sandbox environment, uses the Worldpay sandbox instead of pre-production. This setting is ignored in production

If Worldpay asks for the IP addresses that connect to it, contact support for your instance’s IP addresses. Each instance has its own addresses for each environment.

Mail Order Telephone Order (MOTO)

Worldpay (VAP) differentiates telephone from mail orders with different values for order source. Gr4vy maps all MOTO transactions to telephone.

Capabilities

This connector doesn’t support the Mastercard Transaction Link Identifier (TLID) yet. Worldpay plans to add support in its April 2027 release.

Supported countries

Supported currencies

Each merchant ID (MID) at Worldpay processes payments in one currency. Worldpay processes the amount in that currency, whatever currency the transaction uses. Only send transactions in the currency of the merchant ID (MID) for this connection, and add a separate connection for each currency.

Integration

To accept card payments with Worldpay (VAP), use one of Gr4vy’s client-side integration methods to securely collect card details. Due to PCI compliance requirements, card data should never be sent directly to your servers. You can integrate using:

Embed - A pre-built, customizable payment form that handles the complete payment flow
Secure Fields - Embed card input fields for building custom payment forms while maintaining PCI compliance
Mobile SDKs - Embed SDKs for iOS, Android, and React Native

These methods handle card data collection and tokenization. Once the card details are collected and tokenized, create a transaction through the Gr4vy API, which routes the payment to your configured Worldpay (VAP) connection based on your Flow rules or explicit payment_service_id parameter.

Webhooks

Worldpay (VAP) doesn’t send notifications to Gr4vy. The connection’s webhook URL only receives the refund reports described below.

Report refunds made with Worldpay

A refund you make directly with Worldpay, outside Gr4vy, isn’t recorded in Gr4vy automatically. To record it, turn on refund ingestion for the connection, and then send Gr4vy a request for each refund. Gr4vy has no other way to learn about these refunds, so it only records the refunds you report. Only report refunds that Worldpay approved. Gr4vy records each one as succeeded and doesn’t send anything to Worldpay. Send a POST request to the connection’s webhook URL with the X-Orchestrator-Webhook-Version header set to 1:

POST <webhook URL>
Content-Type: application/json
X-Orchestrator-Webhook-Version: 1

{
  "event": "refund.succeeded",
  "payment_service_capture_id": "100000000000000001",
  "payment_service_refund_id": "100000000000000002",
  "amount": 9900,
  "transaction_reconciliation_id": "7hBqVGJjYkpw8Nf0rLmT2a",
  "raw_response_code": "000",
  "raw_response_description": "Approved",
  "reason": null,
  "external_identifier": null
}

Field	Required	Description
`event`	Yes	Always `refund.succeeded`.
`payment_service_capture_id`	Yes	The `cnpTxnId` that Worldpay returned for the capture you refunded.
`payment_service_refund_id`	Yes	The `cnpTxnId` that Worldpay returned for the refund. Gr4vy stores it as the refund’s `payment_service_refund_id`.
`amount`	Yes	The refunded amount, as a positive integer in the smallest currency unit.
`transaction_reconciliation_id`	No	The `reconciliation_id` of the Gr4vy transaction, if you have it.
`raw_response_code`	No	The `response` code that Worldpay returned for the refund.
`raw_response_description`	No	The `message` that Worldpay returned for the refund.
`reason`	No	A reason for the refund, stored on the refund.
`external_identifier`	No	Your own reference for the refund, stored on the refund.

You can leave out the optional fields or set them to null. Gr4vy checks the request before accepting it:

A valid request returns a 200 response with no body.
A request with a missing or wrong header, a missing or invalid field, or an event other than refund.succeeded returns a 400 response. The JSON body’s message says what’s wrong.

A 200 response means Gr4vy accepted the report, not that it recorded the refund. Gr4vy then matches the refund to the transaction, and the refund ingestion limitations apply. For example, the refund isn’t recorded if refund ingestion is off for the connection. When the refund is recorded, Gr4vy sends a refund.succeeded webhook and adds an External refund reported event to the transaction’s history.

Testing

Worldpay (VAP) offers two test environments. By default, a Worldpay (VAP) connection in a Gr4vy sandbox environment sends requests to Worldpay’s Pre-Live environment. Enable Use sandbox on the connection to send requests to Worldpay’s Sandbox simulator instead. See Certification and Testing Environments for details on both.

Sandbox

The Sandbox is a stateless simulator for functional testing. For card authorizations and sales, the last three digits of the card number set the response code that the simulator returns. For Apple Pay and Google Pay, the last three digits of the amount set the response code. See Testing Response Reason Codes and Messages for the values to use.

Pre-Live

Pre-Live is where Worldpay runs its certification tests. Worldpay publishes the test scenarios and the data each one expects:

Performing the Required Certification Tests.
Performing the Optional Tests, including AVS and card validation, 3DS, prepaid filtering, Apple Pay, and Google Pay.
Test Card Numbers.

Response and validation errors

Worldpay (VAP) returns two kinds of errors:

Payment transaction response codes describe the outcome of a transaction, such as a decline. See Payment Transaction Response Codes.
XML validation errors mean Worldpay rejected the request before processing it. Gr4vy returns these as an invalid_service_request error and includes Worldpay’s message, which names the field that failed validation. See XML Validation Error Messages.

Introduction

Aggregators

Methods

Digital wallets

Anti-fraud

Browse

Worldpay (VAP) - Card

Setup

Connector configuration

Credentials

Mail Order Telephone Order (MOTO)

Capabilities

Supported countries

Supported currencies

Integration

Webhooks

Report refunds made with Worldpay

Testing

Sandbox

Pre-Live

Response and validation errors