Order management

To fit into organizing nature of your business the Order Management is an important part of payments. Order Management enables you to manage all transactions that happen for an order. Easily capture previously authorized funds, void an unsettled transaction, or do a full or partial refund of a settled transaction.

Capture icon

Capture

Full Capture

Fully capturing an order is done when the shipment of all order items is made at once.

Partial capture - final amount is lower after one replacement

A partial capture, that is valued less than the initial order, is done when the value of the shipment is below the order value within the authorize call.

Partial capture - final amount is the same after one replacement

A partial capture, that is valued equally as the initial order, is done when the value of the shipment has the same order value as was used in the authorize call.

Full Capture

This use-case describes fully capturing an order. This can be useful when the shipment is sent in full.

Step 0 - Preconditions

  • One-Step Authorize
  • Order Items Available
  • Full Capture

We have a customer named John. He is shopping the web for two black tablets and one black music player.

Step 1 - John waiting for order

John has either done a One-Step or Two-Step Authorize, and is waiting for his two black tablets and one black music player to be shipped.

imageJohnWaiting

Step 2 - Order can be fulfilled

The merchant checks the supplies and concludes that all the items in the order list are available and ready to be shipped.

imageMerchantCheckingSupplies

Step 3 - Creating a CaptureRequest

To do a full capture, the merchant sends John's order number to the Capture endpoint. The request body does not have to be constructed, because the whole order will be shipped.

NOTE! The endpoint Captures has to be called with the orderNumber in the url.
Resource URL: /api/v3/orders/{orderNumber}/captures


{
  "orderDetails": {}
}
                

Step 4 - AfterPay's response

AfterPay processes the full capture and if the data is correct, responds with 200 "OK".

NOTE! If the response is not successful, common error codes can be found here.

{
  "capturedAmount": 1000.00,
  "authorizedAmount": 1000.00,
  "captureNumber": "XXXXXXXX"
}
                


Partial capture - final amount is lower after one replacement

This use-case describes partially capturing an order. This can be useful when the shipment doesn't match the order and the gross sum is lower.

Step 0 - Preconditions

  • One-Step Authorize
  • Order Partially Sold Out
  • Partial Capture

We have a customer named John. He is shopping the web for two black tablets and one black music player.

Step 1 - John waiting for order

John has either done a One-Step or Two-Step Authorize, and is waiting for his two black tablets and one black music player to be shipped.

imageJohnWaiting

Step 2 - Order cannot be fulfilled

The merchant has discovered that there are only one black tablet and one black music player left. A new supply of black tablets comes in 4 weeks, but it is too long for John to wait. The merchant offers John a white tablet instead of the black one, whereas the white tablet costs 150 euros less.

imageMerchantOfferingReplacement

Step 3 - John agrees with replacement

John thinks a bit, remembers that his wife had actually wanted a white tablet and agrees happily.

imageJohnShakingHandsWithMerchant

Step 4 - Creating a CaptureRequest

Now the merchant has to do a partial capture, overriding the previously authorized order.

To do a partial capture, the merchant creates a CaptureRequest with John's new orderDetails, where one black tablet has been replaced with a white one and the total gross amount has been changed to 850 euros.

NOTE! The endpoint Captures has to be called with the orderNumber in the url.
Resource URL: /api/v3/orders/{orderNumber}/captures

Important variables in this request

totalGrossAmount
decimal
required

Total gross amount must match the SUM of the individual orderItems (grossUnitPrice x quantity).

items
object
required

The items object must be defined, and contain the newly captured order. In this case, the quantity of the black tablets has been reduced and one white tablet has been added.

For more detailed information about this request, visit the Payment's API Documentation.


{
  "orderDetails": {
    "totalNetAmount": 688.5,
    "totalGrossAmount": 850.00,
    "currency": "EUR",
    "imageUrl": "http://testbild.de/orderimg.jpg",
    "items": [
      {
        "productId": "1",
        "groupId": "0022",
        "description": "Tablet Black",
        "netUnitPrice": 324.00,
        "grossUnitPrice": 400.00,
        "quantity": 1.0,
        "vatPercent": 19.0,
        "vatAmount": 76.0,
        "productUrl": "http://testbild.de/productimg.jpg"
      },
      {
        "productId": "1",
        "groupId": "0022",
        "description": "Tablet White",
        "netUnitPrice": 202.5,
        "grossUnitPrice": 250.00,
        "quantity": 1.0,
        "vatPercent": 19.0,
        "vatAmount": 47.5,
        "productUrl": "http://testbild.de/productimg1.jpg"
      },
      {
        "productId": "2",
        "groupId": "0044",
        "description": "MusicPlayer Black",
        "netUnitPrice": 162.0,
        "grossUnitPrice": 200.00,
        "quantity": 1.0,
        "vatPercent": 19.0,
        "vatAmount": 38.0,
        "productUrl": "http://testbild.de/productimg2.jpg"
      }
    ]
  }
}
                    

Step 5 - AfterPay's response

AfterPay processes the partial capture and if the data is correct, responds with 200 "OK".

NOTE! If the response is not successful, here are common error codes.

{
  "capturedAmount": 850.00,
  "authorizedAmount": 1000.00,
  "remainingAuthorizedAmount": 150.00,
  "captureNumber": "XXXXXXXXXX"
}
                

Step 6 - Remaining amount must be voided

Since the white tablet cost 150 euros less, the merchant has to cancel the rest of the order. Please refer to our use-case Full Void on how to do that.

NOTE! The full void is appropriate in this case because the important part of John's order is already captured. In this case, the full void will cancel only the remaining authorized amount of 150 euros.


{{BASE_URL}}/api/v3/orders/{{orderNumber}}/voids
                    


Partial capture - final amount is the same after one replacement

This use-case describes partially capturing an order. This can be useful when the shipment doesn't match the order but the gross sum is still the same.

Step 0 - Preconditions

  • One-Step Authorize
  • Order Partially Sold Out
  • Order Item Replacement
  • Partial Capture

We have a customer named John. He is shopping the web for two black tablets and one black music player.

Step 1 - John waiting for order

John has either done a One-Step or Two-Step Authorize, and is waiting for his two black tablets and one black music player to be shipped.

imageJohnWaiting

Step 2 - Order cannot be fulfilled

The merchant has discovered that there are only one black tablet and one black music player left. A new supply of black tablets comes in 4 weeks, but it is too long for John to wait. The merchant offers John a white tablet instead of the black one, for the same price.

imageMerchantOfferingReplacement

Step 3 - John agrees with replacement

John thinks a bit, remembers that his wife had actually wanted a white tablet and agrees happily.

imageJohnShakingHandsWithMerchant

Step 4 - Creating a CaptureRequest

Now the merchant has to do a partial capture, overriding the previously authorized order. Since the gross sum is the same, it is not a problem.

To do a partial capture, the merchant creates a CaptureRequest with John's new orderDetails, where one black tablet has been replaced with a white one.

NOTE! The endpoint Captures has to be called with the orderNumber in the url.
Resource URL: /api/v3/orders/{orderNumber}/captures

Important variables in this request

totalGrossAmount
decimal
required

Total gross amount must match the SUM of the individual order items (grossUnitPrice x quantity).

items
object
required

The items object must be defined, and contain the newly captured order. In this case, the quantity of the black tablet has been reduced and one white tablet has been added.

For more detailed information about this request, visit the Payment's API Documentation.


{
  "orderDetails": {
    "totalNetAmount": 810.00,
    "totalGrossAmount": 1000.00,
    "currency": "EUR",
    "imageUrl": "http://testbild.de/orderimg.jpg",
    "items": [
      {
        "productId": "1",
        "groupId": "0022",
        "description": "Tablet Black",
        "netUnitPrice": 324.00,
        "grossUnitPrice": 400.00,
        "quantity": 1.0,
        "vatPercent": 19.0,
        "vatAmount": 76.0,
        "productUrl": "http://testbild.de/productimg.jpg"
      },
      {
        "productId": "1",
        "groupId": "0022",
        "description": "Tablet White",
        "netUnitPrice": 324.0,
        "grossUnitPrice": 400.00,
        "quantity": 1.0,
        "vatPercent": 19.0,
        "vatAmount": 76.0,
        "productUrl": "http://testbild.de/productimg1.jpg"
      },
      {
        "productId": "2",
        "groupId": "0044",
        "description": "MusicPlayer Black",
        "netUnitPrice": 162.0,
        "grossUnitPrice": 200.00,
        "quantity": 1.0,
        "vatPercent": 19.0,
        "vatAmount": 38.0,
        "productUrl": "http://testbild.de/productimg2.jpg"
      }
    ]
  }
}
                

Step 5 - AfterPay's response

AfterPay processes the partial capture and if the data is correct, responds with 200 "OK".

NOTE! If the response is not successful, here are common error codes.

{
  "capturedAmount": 1000.00,
  "authorizedAmount": 1000.00,
  "captureNumber": "XXXXXXXXXX"
}