Documentation
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
https://api.paymentwall.com/api/delivery
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
POST
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 |
Statuses
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
PHP
<?php
// Paymentwall PHP Library: https://www.paymentwall.com/lib/php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
'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]' => 'user@hostname.com',
'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
curl https://api.paymentwall.com/api/delivery \
-H "X-ApiKey: [YOUR_PRIVATE_API_KEY]" \
-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]=user@hostname.com"
-d "reason=none"
Node.js
'use strict';
var HttpAction = require('paymentwall/lib/HttpAction'),
util = require('util'),
querystring = require('querystring'),
ApiObject = require('paymentwall/lib/ApiObject'),
Paymentwall = require('paymentwall');
Paymentwall.Configure(
Paymentwall.Base.API_GOODS,
'YOUR_PROJECT_KEY ',
'YOUR_SECRET_KEY '
);
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]" : "user@hostname.com",
"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) {
console.log(response.error);
console.log(response.notices);
}
});