Authorize and Capture

When accepting your first payment, you explored a one-step payment flow in which you immediately transferred the charged amount to your acquiring bank. It is also quite common, however, to temporarily lock the funds for a particular payment and only transfer the funds at a later stage. This is known as a two-step, or Authorize-Capture, payment flow: your customer authorizes the payment during checkout, but you only transfer (capture) the funds to your acquiring bank when the goods or services are delivered.

Bear in mind that you need to capture the funds within a specific time period, or else the hold on the funds will be automatically released. This time period differs per provider. Refer to your provider documentation for more information.

Provider Support

The requests described below are not necessarily supported by all providers. To see which requests are supported by a specific provider, refer to the relevant Provider Integration Guide in the menu on the left.

Let’s proceed to create an authorize-capture flow. If you imported our Postman Collection, you can follow-along with the examples by invoking the requests in the Authorize-Capture folder.

Step 1: Create the Payment

As you may recall, the first step in a payment flow is always to create a payment using the Create Payment API.

Payment Object

The Create Payment API creates a payment object. The payment object provides a single reference to all the transactions that make up a payment. For more information, see Understanding the Payment Object.

Create the payment like so:

javascript
curl

    var request = new XMLHttpRequest();
    request.open('POST', 'https://api.paymentsos.com/payments');
    request.setRequestHeader('Content-Type', 'application/json');
    request.setRequestHeader('api-version', '1.3.0');
    request.setRequestHeader('x-payments-os-env', 'test');
    request.setRequestHeader('app-id', 'com.zooz.docapp');
    request.setRequestHeader('private-key', 'bede7ee5-eaaq-4c9a-bc1f-617ba28256ae');
    request.setRequestHeader('idempotency-key', 'cust-34532-trans-001356-p');
    var body = {
      'amount': 34800,
      'currency': 'EUR',
      'statement_soft_descriptor': 'Oil lamp'};
    request.send(JSON.stringify(body));

    curl --compressed -X POST \
    https://api.paymentsos.com/payments \
    -H 'Content-Type: application/json' \
    -H 'api-version: 1.3.0' \
    -H 'x-payments-os-env: test' \
    -H 'app-id: com.zooz.docapp' \
    -H 'private-key: bede7ee5-eaaq-4c9a-bc1f-617ba28256ae' \
    -H 'idempotency-key: cust-34532-trans-001356-p' \
    -d '{
    "amount": 31602077,
    "currency": "EUR",
    "statement_soft_descriptor": "Oil lamp"
    }'

Step 2: Authorize the Payment

The next step is to authorize the payment using the Create Authorization API. This will temporarily lock the funds for the payment. Here’s an example:

javascript
curl

    var request = new XMLHttpRequest();
    request.open('POST', 'https://api.paymentsos.com/payments/{payment_id}/authorizations');
    request.setRequestHeader('Content-Type', 'application/json');
    request.setRequestHeader('api-version', '1.3.0');
    request.setRequestHeader('x-payments-os-env', 'test');
    request.setRequestHeader('app-id', 'com.zooz.docapp');
    request.setRequestHeader('private-key', 'bede7ee5-eaaq-4c9a-bc1f-617ba28256ae');
    request.setRequestHeader('idempotency-key', 'cust-34532-trans-001356-a');
    var body = {
      'payment_method': {
        'type': 'tokenized',
        'token': '9640e09b-85d0-4509-a19c-90aa65eb386a',
        'credit_card_cvv': '1231'},
      'reconciliation_id': '23434534534'};
  request.send(JSON.stringify(body));

    curl --compressed -X POST \
    https://api.paymentsos.com/payments/{payment_id}/authorizations \
    -H 'Content-Type: application/json' \
    -H 'api-version: 1.3.0' \
    -H 'x-payments-os-env: test' \
    -H 'app-id: com.zooz.docapp' \
    -H 'private-key: bede7ee5-eaaq-4c9a-bc1f-617ba28256ae' \
    -H 'idempotency-key: cust-34532-trans-001356-p' \
    -d '{
    "payment_method": {
      "type": "tokenized",
      "token": "9640e09b-85d0-4509-a19c-90aa65eb386a",
      "credit_card_cvv": "1231"
    },
    "reconciliation_id": "23434534534"
  }'

Notes

If you are SAQ D compliant, you can pass full credit card details without using our tokenization service. To do so, you must pass a payment method type of untokenized and a source_type of credit_card in the request body. For the complete body structure, see the Create Authorization request in the Payments API reference.
If you use an external MPI (merchant plug-in) to authorize a card using 3D Secure, then you can pass the 3DS data returned from the MPI in the three_d_secure_attributes.external object of a Create Authorization or Create Charge request. This requires that you configure a route rule to direct the request to a provider that can process data received from an external 3DS service. For more information, see Routing Transactions to a Provider Supporting External 3DS.

Step 3: Capture the Funds

When you’re ready to transfer the funds, issue a Create Capture API request:

javascript
curl

    var request = new XMLHttpRequest();
    request.open('POST', 'https://api.paymentsos.com/payments/{payment_id}/captures');
    request.open('POST', url);
    request.setRequestHeader('Content-Type', 'application/json');
    request.setRequestHeader('api-version', '1.3.0');
    request.setRequestHeader('x-payments-os-env', 'test');
    request.setRequestHeader('app-id', 'com.zooz.docapp');
    request.setRequestHeader('private-key', 'bede7ee5-eaaq-4c9a-bc1f-617ba28256ae');
    request.setRequestHeader('idempotency-key', 'cust-34532-trans-001356-cap');
    request.send();

    curl --compressed -X POST \
    https://api.paymentsos.com/payments/{payment_id}/captures \
    -H 'Content-Type: application/json' \
    -H 'api-version: 1.3.0' \
    -H 'x-payments-os-env: test' \
    -H 'app-id: com.zooz.docapp' \
    -H 'private-key: bede7ee5-eaaq-4c9a-bc1f-617ba28256ae' \
    -H 'idempotency-key: cust-34532-trans-001356-p' \
    -d '{
  }'

Last modified January 4, 2022