Authorization, captures and voiding

Payment methods like credit-card and klarna-pay-later support authorizations. Authorizations require some extra steps. Many other payment methods result in a sale that is directly payed in full. An authorization is only telling you that you are allowed to capture the provided amount. If you don’t capture the amount the authorization will eventually expire.

Starting an authorization

The example below will create an authorization. The capture_mode is set to manual. The customer authorizes by following the steps via the payment url. Once you are authorized the order still has to be captured.

Passing an expiration period in the transaction is advised but not required. If you do not pass the expiration_period the default value configured in the platform will be used. For example, a klarna-pay-later will expire in 48 hours and for credit-card only 30 minutes. If the transaction has expired, no captures can be made.

The order line type must be one of physical, discount, shipping_fee, sales_tax, digital, gift_card, store_credit or surcharge.

POST /v1/orders/
{
    "amount": 10000,
    "currency": "EUR",
    "description": "Example Klarna order",
    "order_lines": [
        {
            "type": "physical",
            "amount": 5000,
            "currency": "EUR",
            "merchant_order_line_id": "0001",
            "name": "Example article",
            "quantity": 2,
            "vat_percentage": 2100
        }
    ],
    "transactions" : [{
        "payment_method": "klarna-pay-later",
        "expiration_period": "P7D",
        "capture_mode": "manual"
    }]
}

Capture in full

The request below will capture an authorized transaction in full. No body is required.

POST /v1/orders/<order_id>/transactions/<transaction_id>/captures/

Capture order lines

The request below will capture a single item of the first order line. The remaining uncaptured quantity wil be 1. Once you did a capture based on an order line, you can only continue capturing order lines. Capturing based on the amount is then not available anymore.

POST /v1/orders/<order_id>/transactions/<transaction_id>/captures/orderlines/
{
  "description": "Capture 1 of order line 0001",
  "order_lines": [
      {
          "merchant_order_line_id": "0001",
          "quantity": 1
      }
  ]
}

Capture amount

The request below will capture 2500. Once you did a capture based on an amount, you can only continue capturing amounts. Capturing based on order lines is then not available anymore.

POST /v1/orders/<order_id>/transactions/<transaction_id>/captures/amount/
{
  "amount": 2500
  "description": "Capture 2500 of the full 10000"
}

Voiding

Voiding reduces the authorization amount, this should be done when a part of the authorization is no longer required. An authorization can be voided partially or in full. In our example authorization there’s a quantity of two for “Example article”. If only one of two can be delivered the remaining amount can be voided.

Void using order lines

The request below voids a single item of the order line 0001. The remaining amount will be half.

POST /v1/orders/<order_id>/transactions/<transaction_id>/voids/orderlines/
{
  "description": "Void 1 of order line 0001",
  "order_lines": [
      {
          "merchant_order_line_id": "0001",
          "quantity": 1
      }
  ]
}

Void using amount

The request below voids based on an amount. The authorization will be reduced by 2500.

POST /v1/orders/<order_id>/transactions/<transaction_id>/voids/amount/
{
  "amount": 2500
  "description": "Void 2500 of the full 10000"
}

Auto capture delayed

There are certain cases where you want to automatically capture after a certain time. In the example below we set capture_mode=delayed and expiration_period=P7D (7 days). When the customer authorizes the transaction below it will be captured in 7 days. No manual captures can be done on an order that is created with capture_mode=delayed.

POST /v1/orders/
{
    "amount": 10000,
    "currency": "EUR",
    "description": "Example Klarna order",
    "order_lines": [
        {
            "amount": 5000,
            "currency": "EUR",
            "merchant_order_line_id": "0001",
            "name": "Example article",
            "quantity": 2,
            "vat_percentage": 2100
        }
    ],
    "transactions" : [{
        "payment_method": "klarna-pay-later",
        "expiration_period": "P7D",
        "capture_mode": "delayed"
    }]
}

Voiding a delayed capture

It’s possible to prevent capturing a delayed capture. You can void the amount or order lines that don’t need to be captured.

Show status of order line

With an authorization order order lines can be capture, voided or authorized. To get a view of the status of an order line an order can be requested with an additional parameter ?fields[]=order_line_details

{
	# ...
	"order_line_details": [
		{
			"amount": "1",
			"currency": "EUR",
			"merchant_order_line_id": "0001",
			"name": "Example article",
			"quantity": "10",
			"status": "authorized",
			"type": "physical",
			"vat_percentage": "0"
		},
		{
			"amount": "1",
			"currency": "EUR",
			"merchant_order_line_id": "0001",
			"name": "Example article",
			"quantity": "10",
			"status": "captured",
			"type": "physical",
			"vat_percentage": "0"
		},
		{
			"amount": "1",
			"currency": "EUR",
			"merchant_order_line_id": "0001",
			"name": "Example article",
			"quantity": "10",
			"status": "voided",
			"type": "physical",
			"vat_percentage": "0"
		},
		{
			"amount": "102",
			"currency": "EUR",
			"merchant_order_line_id": "0002",
			"name": "Example article",
			"quantity": "1",
			"status": "voided",
			"type": "physical",
			"vat_percentage": "0"
		}
	]
}

Show amounts remaining, captured and voided

Within an authorization order the amount captured, remaining and voided can be requested. This is done by appending the query parameter ?fields[]=amount_details

{
	# ... 
	"amount_details": {
		"captured": 0,
		"original": 112,
		"remaining": 0,
		"voided": 112
	}
}