Pay with card

Card payments run through the processor’s hosted fields, either CyberSource Flex or Mastercard MPGS. The customer types the card number and security code into fields served by the processor, inside your page. Vestrapay never receives the card number or CVV, and neither do your servers, which keeps card data off your systems and reduces your PCI burden. Hosted checkout does all of this for you. This page is for teams building a custom pay screen with the access code.

If you use hosted checkout, you do not need anything on this page. Redirect to the checkout URL and verify the result. Read on only if you are building your own card form.

How a card payment flows

A card payment is a short state machine. You call one endpoint, read data.status from the response, and the status tells you what to do next.

Step by step

Initialise

Create the payment on your server. Keep data.accessCode and data.reference. Hand the access code, and only the access code, to your browser code.

Create a card session

From the browser, or from a checkout backend that holds the access code, ask Vestrapay to prepare the hosted fields.

curl -X POST https://api.sandbox.vestrapay.app/v1/payment/checkout/card/session \
  -H "x-access-code: ACCESS_CODE"

The response says which processor is active in hostedCard.provider, which is cybersource or mpgs, and gives the configuration for it:

{
  "status": "success",
  "data": {
    "sessionId": "FLEX_OR_MPGS_SESSION",
    "reference": "VPY_TXN_ACME001",
    "hostedCard": {
      "provider": "cybersource",
      "scriptUrl": "https://…",
      "captureContext": "eyJ…"
    }
  }
}

The values shown are illustrative. Always use the script URL and capture context the response gives you. Do not hard-code them.

Mount the hosted fields

CyberSource. Load hostedCard.scriptUrl, create the microform with new Flex(hostedCard.captureContext).microform(), and mount the number and security code fields only. Keep the expiry month and year as your own inputs. When the customer submits, call createToken({ expirationMonth, expirationYear }). The token it returns is a JWT, and it is what you send as sessionId on charge.MPGS. Load hostedCard.scriptUrl and mount Mastercard’s hosted fields against the session ID from the response.Whichever processor is active, only the processor sees the card number and CVV.

Charge

Send the session value and the browser details the issuer needs for 3-D Secure.

curl -X POST https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card \
  -H "x-access-code: ACCESS_CODE" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "FLEX_OR_MPGS_SESSION",
    "browser": "Mozilla/5.0 …",
    "browserDetails": {
      "screenHeight": 982,
      "screenWidth": 1512,
      "colorDepth": 24,
      "javaEnabled": false,
      "language": "en-GB",
      "timeZone": -60
    }
  }'

transientToken is accepted as an alias of sessionId for CyberSource. If you send neither, Vestrapay uses the token stored when the session was created.Fill browserDetails from the real browser: screen height and width, colour depth, whether Java is enabled, the language tag, and the time zone offset in minutes from new Date().getTimezoneOffset(). Send accurate values, because the issuer uses them when it assesses the risk of the payment.

Branch on data.status

The call returns HTTP 201 with an outer status of success even when the card is declined, because the call worked. The outcome is data.status.

`data.status`	What to do
`fingerprint_required`	Inject `data.fingerprintHtml` into a hidden iframe. Wait for device data to be collected, or for about 12 seconds, then call authenticate.
`3ds_required`	Inject `data.threeDsHtml` into an on-page frame of roughly 390 by 400 pixels so the customer can complete the issuer challenge.
`success`	The processor reports the payment as paid. Show a receipt, and confirm with verify on your server.
`failed`	Show `data.message`. Let the customer try another card, with a new card session.
`processing`	Do not fulfil. Wait for the checkout event or the webhook, or poll verify.

A typical success response:

{
  "status": "success",
  "data": {
    "status": "success",
    "reference": "VPY_TXN_ACME001"
  }
}

A failed attempt has the same shape with data.status set to failed and a data.message you can show to the customer.

3-D Secure after fingerprinting

Call authenticate only when charge returned data.status of fingerprint_required. No session ID is needed because it is already stored against the payment.

curl -X POST https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card/authenticate \
  -H "x-access-code: ACCESS_CODE" \
  -H "Content-Type: application/json" \
  -d '{ "browser": "Mozilla/5.0 …" }'

The response has the same shape as a charge. data.status is success, failed, or 3ds_required with data.threeDsHtml for the challenge. When the issuer challenges the customer, the challenge iframe posts back to Vestrapay’s 3-D Secure callback. That is not your callbackUrl. The callback page then notifies your page, which is the parent window, with a message:

{
  "type": "vestrapay.3ds.complete",
  "reference": "VPY_TXN_ACME001",
  "status": "success",
  "message": null
}

Listen for that message on the window, check type, and then call verify through your server. As a fallback, also watch the checkout event checkout.completed on GET /v1/payment/checkout/events, in case the message is lost.

Constraints that matter

Card number and CVV go to the hosted fields only. Never build your own input for them.
Run the 3-D Secure challenge in an on-page iframe. Do not use window.open, because pop-up blockers and the loss of the message channel break the flow.
Keep the top-level window on your own checkout origin throughout 3-D Secure. Navigating away abandons the callback.
Call authenticate only after fingerprint_required. Calling it at any other time fails.
Processor sessions are single use. After a failed charge, create a new card session before the customer retries. Reusing the old one returns card.retry_session_required.
Each payment allows a limited number of charge attempts. When they run out, charge returns payment.max_attempts_exceeded and you must initialise a new payment.
Fulfil only after verify says success. The charge response is the processor’s word, and your server’s verify call is the confirmation.

Failure modes

Situation	Behaviour	What to do
Issuer declines the card	`data.status` is `failed`, or the call returns `card.declined` with the issuer’s message	Show the message. Offer another card with a new session.
Hosted field script fails to load	No session to charge	Offer retry or switch the customer to transfer.
Customer closes the page during 3-D Secure	The payment stays unfinished and later becomes `abandoned`	Do not fulfil. Let them start again.
Access code expires	`session.expired`	Initialise a new payment.
Processor outage	`processor.unavailable` or `card.processor_error`	Retry with backoff, or offer transfer.

See Errors for the full catalogue.

Test cards

On the sandbox mock card processor, 4111111111111111 and 4242424242424242 succeed. Any other number is rejected. Use a future expiry and any security code. When CyberSource or MPGS is the active test processor, use that processor’s own test card numbers instead. More on Test payments.

Get started

Accept payments

Services & splits

Partners

Settlements

How a card payment flows

Step by step

3-D Secure after fingerprinting

Constraints that matter

Failure modes

Test cards

​How a card payment flows

​Step by step

​3-D Secure after fingerprinting

​Constraints that matter

​Failure modes

​Test cards

How a card payment flows

Step by step

3-D Secure after fingerprinting

Constraints that matter

Failure modes

Test cards