Paymentwall website uses cookies to store your browsing preferences on your device. However, cookies do not collect personal information.

For more information about how we use cookies, check our cookie policy



New Documentation Getting Started API Libraries APIs Checklists Flows Integrations Mobile SDKs Reference Smart TV SDK SpiderPipe Testing Payments
If you still have questions regarding integration, please email us at

Delivery Confirmation API

API Description

Delivery Confirmation API allows merchants to notify Paymentwall about successful delivery of the purchased item(s) to the user. This information helps us resolve dispute cases and refund requests in the fastest and the most efficient manner.

API Endpoint

Authentication HTTP Header

The API expects the Private API key to be sent as custom HTTP header "X-ApiKey". For example, "X-ApiKey: YOUR_PRIVATE_KEY".

Please note that the Private API key can only be used for server-to-server calls and should never be exposed to end-users.

Paymentwall is also expecting header Content-Type: application/x-www-form-urlencoded.

Request Method


Request Parameters

parameter required description
payment_id yes Paymentwall reference ID of the payment, e.g. b123123123. You can get payment_id from pingback 'ref' param
merchant_reference_id no merchant internal reference ID
type yes type of delivery - either physical or digital
is_test no 1 for test API calls, 0 for production API calls
carrier_tracking_id yes for physical
carrier_type yes for physical carrier, see carriers
status yes see statuses
estimated_delivery_datetime yes estimated delivery date, format: 2015/01/20 15:04:55 +0300
estimated_update_datetime yes when the next status update is planned, format: 2015/01/15 15:04:55 +0300
status_changed_datetime no can only be activated per request, updates have to be realtime
reason yes additional reason for status
refundable yes true / false - whether the order is still refundable at this stage
received_by yes for status delivered for physical Initials of the person received the delivery
attachments yes array of attachments such as proofs of delivery, files are expected (see code samples to refer how to send)
details yes message about status update visible to Paymentwall and recipient
product_description yes in case the product was substituted, changed or altered
shipping_address[country] yes for physical shipping address country, ISO alpha-2 code
shipping_address[city] yes for physical shipping address city
shipping_address[zip] yes for physical shipping address zip/postal code
shipping_address[state] yes for physical shipping address state or province if applicable
shipping_address[street] yes for physical shipping address street
shipping_address[phone] yes for physical shipping phone number
shipping_address[email] yes shipping email
shipping_address[firstname] yes for physical shipping firstname
shipping_address[lastname] yes for physical shipping lastname
recipient_feedback no freeform data about user satisfaction


status description
order_placed Order has been placed within merchants system, this status should be sent immediately after receiving a pingback.
order_preparing Merchant started to look for ordered item in stock, processing the order.
started The delivery has been started.
delivering Item is being delivered.
delivered Item delivered to the end-user, transaction complete. Attachment with a proof of delivery is expected in this case.
consumed Item is consumed by the end-user. Example: activation key was used to unlock the software, virtual currency was used up to buy an in-game item.
waiting_user_action User's action is requested to complete the delivery, e.g. check the item or pick it up.
delayed Delay in delivery. Details parameters need to contain the reason.
failed_will_retry Delivery to end user failed. Waiting for retry.
order_cancelled Ordered has been cancelled and wait for refund or substitution. Details parameters need to contain the reason. Reason needs to be supplied, e.g. "out of stock"
retry_started Attempt to retry on delivery.
refund_requested End user made a refund request on the order.
refund_request_declined Merchant decline request to refund. Details parameters need to contain the reason.
refund_request_accepted Order will be refunded. Details parameters need to contain the "details" (this would be alternative refund or payment refund)
refund_issued The original payment has been refunded. Details parameters can be specified using "details", specifying e.g. "Partial refund has been issued for payment b123123123" or "User's in-service balance was increased by 1000 coins for further payments". In case the original payments needs to be refunded, a separate API call via Refund or Cancellation API needs to be made.
cancelled_subscription Cancel Subscription.
substitution_requested Changes need to be made to the order after paid. Details parameters need to contain the "reason"
substitution_accepted Changes have been accepted by merchant, and will be given, next extected status - delivery_started or order_preparing
substitution_declined Changes has been declined by the merchant. Details parameters need to contain the "reason".

Code Samples


// Paymentwall PHP Library:
    'private_key' => '[YOUR_PRIVATE_API_KEY]'
$delivery = new Paymentwall_GenerericApiObject('delivery');
$response = $delivery->post(array(
    'payment_id' => 'b63400368',
    'merchant_reference_id' => 'order_12345',
    'type' => 'digital',
    'status' => 'delivered',
    'estimated_delivery_datetime' => '2015/01/15 15:00:00 +0300',
    'estimated_update_datetime' => '2015/01/15 11:00:00 +0300',
    'refundable' => true,
    'details' => 'Item will be delivered via email by 3PM on 2015/01/15',
    'shipping_address[email]' => '',
    'reason' => 'none',
    'attachments[0]' => '@/usr/local/www/content/proof/b63400368/1.png',
    'attachments[1]' => '@/usr/local/www/content/proof/b63400368/2.png',
if (isset($response['success'])) {
    // delivery status is successfully saved
} elseif (isset($response['error'])) {
    var_dump($response['error'], $response['notices']);


curl \
-d "payment_id=b63400368" \
-d "merchant_reference_id=order_12345" \
-d "type=digital" \
-d "status=started" \
-d "is_test=1" \
-d "estimated_delivery_datetime=2015/06/15 15:04:55" \
-d "estimated_update_datetime=2015/07/16 15:04:55 +0500" \
-d "refundable=false" \
-d "details=Item will be delivered via email by 3PM on 2015/01/15" \
-d "shipping_address[email]"
-d "reason=none"


'use strict';
var HttpAction = require('paymentwall/lib/HttpAction'),
    util = require('util'),
    querystring = require('querystring'),
    ApiObject = require('paymentwall/lib/ApiObject'),
    Paymentwall = require('paymentwall');


var api = new ApiObject();
api.createDeliveryRequest = function() {
    var url = this.BRICK_BASE_URL;
    var method = 'POST';
    var post_options = this.createPostOptions(url, '/api/delivery', method);
    return post_options;

var post_options = api.createDeliveryRequest();

var post_data = {
    "payment_id" : "b63400368",
    "merchant_reference_id" : "order_12345",
    "type" : "digital",
    "status" : "delivered",
    "estimated_delivery_datetime" : "2018/08/23 15:00:00 +0300",
    "estimated_update_datetime" : "2018/08/23 11:00:00 +0300",
    "refundable" : true,
    "details" : "Item will be delivered via email by 3PM on 2018/08/23",
    "shipping_address[email]" : "",
    "reason" : "none",
    "attachments" : {}

post_data = querystring.stringify(post_data);

HttpAction.runAction(post_options, post_data, true, function(response) {
    response = response.JSON_chunk;
    if(response.success) {
        // delivery status is successfully saved
    } else if(response.error) {
This page needs JavaScript
Your browser is
not supported anymore.
Please update to the more recent one.
This page needs JavaScript
This page needs JavaScript.
Please enable it in your browser settings and try again.
We use cookies on this website to make your browsing experience better. By using the Paymentwall website you agree to our Cookies Policy.