Charge a card

Submits the token or session produced by the hosted fields, together with the browser details the issuer needs for 3-D Secure.

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

`data.status`	What to do
`fingerprint_required`	Inject `data.fingerprintHtml` into a hidden iframe, wait for device data (or 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.
`processing`	Do not fulfil. Wait for the checkout event or the webhook, or poll verify.
`success`	The processor reports the payment as paid. Show a receipt, then confirm with verify on your server.
`failed`	Show `data.message`. Offer another card, with a new card session.

Run the 3-D Secure challenge in an on-page iframe. Do not use a pop-up window. Each payment allows a limited number of charge attempts. When they run out the call fails with payment.max_attempts_exceeded and you must initialise a new payment.

On the sandbox mock processor, 4111111111111111 and 4242424242424242 succeed and any other number is rejected. When CyberSource or MPGS is the active test processor, use that processor’s own test cards.

POST

payment

checkout

charge

card

Charge a card

curl --request POST \
  --url https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card \
  --header 'Content-Type: application/json' \
  --header 'x-access-code: <api-key>' \
  --data '
{
  "sessionId": "FLEX_OR_MPGS_SESSION",
  "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  "browserDetails": {
    "screenHeight": 982,
    "screenWidth": 1512,
    "colorDepth": 24,
    "javaEnabled": false,
    "language": "en-GB",
    "timeZone": -60
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-access-code': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sessionId: 'FLEX_OR_MPGS_SESSION',
    browser: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
    browserDetails: {
      screenHeight: 982,
      screenWidth: 1512,
      colorDepth: 24,
      javaEnabled: false,
      language: 'en-GB',
      timeZone: -60
    }
  })
};

fetch('https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card"

payload = {
    "sessionId": "FLEX_OR_MPGS_SESSION",
    "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browserDetails": {
        "screenHeight": 982,
        "screenWidth": 1512,
        "colorDepth": 24,
        "javaEnabled": False,
        "language": "en-GB",
        "timeZone": -60
    }
}
headers = {
    "x-access-code": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'sessionId' => 'FLEX_OR_MPGS_SESSION',
    'browser' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
    'browserDetails' => [
        'screenHeight' => 982,
        'screenWidth' => 1512,
        'colorDepth' => 24,
        'javaEnabled' => false,
        'language' => 'en-GB',
        'timeZone' => -60
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-access-code: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

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

Authorizations

x-access-code

string

header

required

The accessCode returned by initialise. Scoped to one payment and valid for 60 minutes. Safe to give to the customer's browser.

Body

application/json

The card token or session, and the browser details the issuer uses to assess risk.

sessionId

string

The CyberSource token returned by the microform, or the MPGS session ID. If you send neither this nor transientToken, Vestrapay uses the token stored when the session was created.

transientToken

string

An alias of sessionId for CyberSource.

browser

string

The browser user agent string.

browserDetails

object

Read these from the real browser. Accurate values help the issuer approve the payment.

Show child attributes

Response

Charge result. Read data.status.

The outer status is success whenever the call worked, even when the card was declined. The outcome is data.status.

status

enum<string>

required

Available options:

success

data

object

required

Show child attributes

Charge a card

curl --request POST \
  --url https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card \
  --header 'Content-Type: application/json' \
  --header 'x-access-code: <api-key>' \
  --data '
{
  "sessionId": "FLEX_OR_MPGS_SESSION",
  "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  "browserDetails": {
    "screenHeight": 982,
    "screenWidth": 1512,
    "colorDepth": 24,
    "javaEnabled": false,
    "language": "en-GB",
    "timeZone": -60
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-access-code': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sessionId: 'FLEX_OR_MPGS_SESSION',
    browser: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
    browserDetails: {
      screenHeight: 982,
      screenWidth: 1512,
      colorDepth: 24,
      javaEnabled: false,
      language: 'en-GB',
      timeZone: -60
    }
  })
};

fetch('https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card"

payload = {
    "sessionId": "FLEX_OR_MPGS_SESSION",
    "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browserDetails": {
        "screenHeight": 982,
        "screenWidth": 1512,
        "colorDepth": 24,
        "javaEnabled": False,
        "language": "en-GB",
        "timeZone": -60
    }
}
headers = {
    "x-access-code": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/card",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'sessionId' => 'FLEX_OR_MPGS_SESSION',
    'browser' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
    'browserDetails' => [
        'screenHeight' => 982,
        'screenWidth' => 1512,
        'colorDepth' => 24,
        'javaEnabled' => false,
        'language' => 'en-GB',
        'timeZone' => -60
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-access-code: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

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

Payments

Checkout

Charge a card

Authorizations

Body

Response