Merchant API documentation

Introduction

The boxPAY Merchant API provides a secure means for merchants to interact with the boxPAY platform to query merchant specific information for one-off and subscription services. This document describes the API calls that can be used for all types of services as well as additional functionalities available for subscription services and steps required to enable subscription services.

Prerequisites for Subscription

  1. The merchant should liaise with boxPAY (via contact@boxpay.com or through direct channels) to agree on the relevant subscription models, based on:
    • Price point
    • Billing frequency (in days) - Please note that the first billing cycle is the initial payment made through the payment box – (or via the standard API). Subsequent billing cycles are handled by boxPAY and will be a number of days after the initial billing, as defined by the billing frequency.
  2. The merchant requires approval from boxPAY before a subscription service is enabled. The subscription service is assigned to a specific merchant payment box. This should be set up as normal through the boxpay.com website, noting that only 1 payment item can be used for any given country.

Additional Integration for Subscription

In addition to the default integration as detailed in the merchant portal at www.boxpay.com, the following additions are applicable to subscription services:

  1. Payment Status Notification – The subscription status is an additional parameter that is passed to the merchant in the client side “RedirectUrl” and the server to server request via the Notification URL (as set in the payment box setup). The parameter name is SubStatus. Possible values are defined in Appendix B (Subscription Status). Note that the status of the subscription in no way affects the status of the payment session itself and conversely the status of the payment does not completely affect the status of the subscription. E.g Even if the payment fails, the customer can still be successfully subscribed to the service. E.g the user may opt in but have insufficient credit to make the initial payment.
  2. The Subscription API calls described in this document. This allows the merchant to:
    • Get a list of subscribers (active and inactive) for a given service (via GetSubscribers call)
    • For any given subscriber, retrieve the subscriber’s spend on a given day
    • Remove a subscriber from the subscription (via Unsubscribe call) – This will cancel a user’s subscription
  3. Subscription Notification – This is to notify the merchant that a periodic transaction for a subscription service has taken place and that the merchant’s user has been charged. This notification should be used to credit the user’s account with the appropriate service. Please see the information sent to the merchant in Subscription Notification.

API Format and URLs

The API is currently available in SOAP XML via HTTP GET and POST. JSON is also available by using HTTP POST with the request content type set to “application/json”.

The WSDL can be found at
http://api.boxpay.com/merchants/v1_4.asmx?WSDL

Example request and response formats are available at http://api.boxpay.com/merchants/v1_4.asmx

Support

For all support queries, contact support@boxpay.com

General API calls

The following API calls are applicable to both payment models (subscription/one-off payments).

1. CheckStatus

This method is used to check the status of a payment session. It can be called at regular intervals until such time as:

  • The payment is successful or
  • The payment fails or
  • The payment is still pending after a considerable period of time (in such cases the merchant will still be notified of an eventual successful payment via the server side request to the Notification URL)

The merchant should allow at least 2 seconds between each CheckStatus request.

Full details on the format of the request are detailed here: http://api.boxpay.com/ Merchants/v1_4.asmx?op=CheckStatus

Request

Parameter Description Required
SessionId The unique identifier for the payment session, as returned in InitiatePayment. Yes
Signature MD5 Hash of the concatenation of your Private Key and the above parameter values in order shown. MD5(PrivateKey+ SessionId) Yes

Response

Parameter Description
RequestProcessed A Boolean value (true or false) to indicate whether or not the request was processed successfully. This has no bearing on the status of the payment.
ReasonCode An enumeration to give extra details on the reason for the result given by RequestProcessed
AdditionalInfo Additional textual info for debugging purposes
Charged A decimal value indicated the amount of local currency that has been successfully charged to the user.
Status Indicates the success or otherwise of this call. Possible values are:
  • SUCCESS: the request was processed successfully and the payment has been successfully completed. No further action is necessary.
  • PENDING: the request was processed successfully. Payment has not yet been completed (may require user interaction)
  • FAILED: the request and/or payment failed. More details provided in StatusReason
StatusReason Provides extra details on the Status so that appropriate action can be taken. A detailed list of the Reason Codes is provided in Appendix A.
UserMessageHTML An instructional message that should be displayed to the user to direct the user on how to proceed. This can include HTML markup.
MSISDN The user’s mobile number, in international format. E.g a number in the UK will be of the form 447123456789.
NetworkId An integer value indicating the user’s network operator(carrier). A list of NetworkIds and associated networks will be provided on request. The value 0 means as yet unidentified.
SubscriptionStatus Applicable to Subscription Services only (see Appendix B)
ReturnUrl This is the ReturnUrl value passed to boxPAY by the merchant.

2. GetPayouts

This method is used to retrieve the payout to a merchant for all price points in a country.

Full details on the format of the request are detailed here: http://api.boxpay.com/merchants/v1_4.asmx?op=GetPayouts

Request

Parameter Description Required
CountryCode The two-letter ISO country code of the required country Yes
NetworkId An integer value indicating the network operator (carrier). A list of NetworkIds and associated networks will be provided on request. The value 0 can be used to return payouts for all networks Yes
MerchantId Your own merchantId. This is shown in the “Payment Boxes” page in the boxPAY portal. (beside the account email address). Yes
Signature MD5 Hash of the concatenation of your Private Key and the above parameter values in order shown. MD5(PrivateKey+ CountryCode+NetworkId+MerchantId) Yes

Response

Parameter Description
RequestProcessed A Boolean value (true or false) to indicate whether or not the request was processed successfully.
ReasonCode An enumeration to give extra details on the reason for the result given by RequestProcessed
AdditionalInfo Additional textual info for debugging purposes
CountryCode Two letter ISO country code
CurrencyCode The ISO 4217 currency code indicating the local currency
MerchantId Your merchant Id
NetworkId The network Id of the payout amount
Price The end user charge in local currency
Payout The payout in local currency

Subscription API calls

1. GetSubscribers

This method is used to retrieve the list of subscribers for a given service/payment box. A subscriber is any user that was subscribed to the service at any point.

  • Active - still subscribed to the service
  • Inactive - not currently subscribed to the service. User may have stopped (unsubscribed) or been removed by merchant/customer service.

Full details on the format of the request are detailed here: http://api.boxpay.com/merchants/v1_4.asmx?op=GetSubscribers

Request

Parameter Description Required
CountryCode The two-letter ISO country code to denote the country of the payment box/service. Yes
ServiceId The ID of the payment box to query subscription transactions for Yes
SubscriptionStatus This is a filter of the results to return only those active subscriptions or only the inactive instances, or both. -1 = Both Active and Inactive, 1 = Active, 0 = Inactive. Yes
Signature MD5 Hash of the concatenation of your Private Key and the above parameter values in order shown. MD5(PrivateKey+ CountryCode+ServiceId+SubscriptionStatus) Yes

Response

Parameter Description
Active (Boolean) True if subscriber is still subscribed to the service, false otherwise.
LastPaymentCycleDateGMT (DateTime) The date and time of the most recent billing attempt to charge the user.
UnsubscribedDate The date the customer unsubscribed from this subscription. A default value of “1900-01-01” is given if the subscription is still active.
NetworkId An integer value indicating the user’s network operator(carrier). A list of NetworkIds and associated networks will be provided on request. The value 0 means as yet unidentified.
MSISDN The user’s mobile number
PaymentSessionId The initial payment session relating to this subscriber

2. GetSubscriberSummary

This method is used to retrieve payment information for a subscriber on a given day. The returned result contains details on any payment made, after the initial payment, i.e. the initial payment is not included in the result of this API call.

Note: CheckStatus should be used to query the payment information etc for the user’s initial payment

Full details on the format of the request are detailed here: http://api.boxpay.com/merchants/v1_4.asmx?op=GetSubscriberSummary

Request

Parameter Description Required
PaymentSessionId The ID of the payment session that entered the customer into the subscription. Yes
Day A datetime representing any day during which the user may have been charged by the subscription. This will be of the format YYYY- MM-DD, e.g ‘2012-01-31’ Yes
Signature MD5 Hash of the concatenation of your Private Key and the above parameter values in order shown. MD5(PrivateKey+ PaymentSessionId+Day) Yes

Response

Parameter Description
RequestProcessed A Boolean value (true or false) to indicate whether or not the request was processed successfully.
ReasonCode An enumeration to give extra details on the reason for the result given by RequestProcessed
AdditionalInfo Additional textual info for debugging purposes
PaymentCycle An integer value indicating the subscriber’s current payment cycle.
LocalCurrency The ISO 4217 currency code of the payment currency.
HomeCurrency The ISO 4217 currency code of the merchant’s home currency as specified in profile settings in merchant portal.
ExchangeRate The exchange rate from LocalCurrency to HomeCurrency as of the date of LastPaymentCycleDateGMT.
LCSpend The end user charge in local currency
HCSpend The equivalent of LCSpend in the merchant’s home currency based on exchange rate on that day
LCPayout The merchant payout amount in local currency.
HCPayout The equivalent of LCPayout in the merchant’s home currency based on exchange rate on that day
Active (Boolean) True if subscriber is still subscribed to the service, false otherwise.
LastPaymentCycleDateGMT The date of the last recurring payment.
SubscriptionDate The date the user subscribed. (i.e. the Initial Payment Session date)
UnsubscribedDate The date the customer unsubscribed from this subscription. A default value of “1900-01-01” is given if the subscription is still active.
NetworkId An integer value indicating the subscriber’s network.
MSISDN The user’s mobile number
PaymentSessionId The initial payment session relating to this subscriber

3. Unsubscribe

This method is used to cancel a user’s subscription. All pending charges will be cancelled and a confirmation message will be sent to the user (if applicable).

Full details on the format of the request are detailed here: http://api.boxpay.com/Merchants/v1_4.asmx?op=Unsubscribe

Request

Parameter Description Required
InitialPaymentSessionId The unique identifier for the payment session Yes
Signature MD5 Hash of the concatenation of your Private Key and the above parameter values in order shown. MD5(PrivateKey+ InitialPaymentSessionId) Yes

Response

Parameter Description
RequestProcessed A Boolean value (true or false) to indicate whether or not the request was processed successfully.
ReasonCode An enumeration to give extra details on the reason for the result given by RequestProcessed
AdditionalInfo Additional textual info for debugging purposes

Subscription Notification

The subscription notification is a HTTP GET request sent to the “Notification Url” property in payment box setup. This is the same URL used for receiving notifications from boxPAY that the merchant defines in the payment box setup. However, the parameters included in this request differ from the standard notification, as detailed below. The querystring parameters in this request are all prefixed with “Sub”; they are summarised in the following table.

NB – Each notification is a summary of the currently successfully charged amount for a subscriber for a given day.

In some cases boxPAY will send multiple notifications for the same subscriber for the same day – each notification is a snapshot of the current total charged to the subscriber for that day, so the merchant must ensure not to count each notification (for the same SubPSID and SubPaymentCycleDate) as a distinct charge, but instead update the current tally for that subscriber for that day (i.e for that SubPSID and SubPaymentCycleDate). This idempotence means that a notification could be resent without causing duplications in crediting the end-user.

Parameter Description
SubPSID The payment session ID of the initial payment transaction that entered the customer into a subscription. Merchants are to use this to identify the type of service to offer to the end user.
SubPaymentCycleDate The date of this periodic transaction.
SubActive To indicate the status of the subscription. 1 = Active, 0 = Inactive.
SubPaymentCycle An integer value indicating the subscriber’s payment cycle of this subscription. Payment cycle 1 means this notification is for the 1st periodic transaction.
SubLocalCurrency The ISO 4217 currency code of the payment currency.
SubHomeCurrency The ISO 4217 currency code of the merchant’s home currency as specified in profile settings in merchant portal.
SubExchangeRate The exchange rate used to convert SubLocalCurrency to SubHomeCurrency as of SubPaymentCycleDate.
SubLCSpend The current end user charge tally in local currency for this day (given by SubPaymentCycleDate)for this subscriber
SubHCSpend The equivalent of SubLCSpend in the merchant’s home currency based on exchange rate on that day
SubLCPayout The merchant payout amount in local currency
SubHCPayout The equivalent of SubLCPayout in the merchant’s home currency based on exchange rate on that day

Appendix A – Reason Codes

  • None – No extra information
  • AwaitingUserAction – The payment can proceed once the user has completed the appropriate step (determined by the PaymentCaptureMethod). E.g the user must send a message to a shortcode.
  • PaymentItemNotFound – A payment item was not found for the service, country and item code defined.
  • InvalidMSISDN – The MSISDN passed is not in the valid international format required.
  • CountryCodeNotRecognised - The country code was not recognised as a valid ISO 3166-1 alpha-2 code country code.
  • PricepointNotFoundForPaymentItem – No active price point was found for the settings provided. Action: Check payment box settings and ensure appropriate values are passed.
  • PaymentItemDescriptionNotFound – The description for the payment item was not found.
  • ItemCodeNotValid – The item code was not provided PricepointNotFound – No active price point was found.
  • LanguageCodeNotRecognised – The language code provided was not recognised as a valid 2- character ISO 639-1 code
  • MerchantNotFound – A valid merchant was not found. Action: Check that the correct ServiceId is being passed.
  • InvalidSignature – The signature does not match. Action: Check that the signature is being generated with the appropriate arguments in the correct order.
  • PaymentSuccessful – The payment is successful. No further action is required.
  • InvalidSessionId – The SessionId value provided is not a valid SessionId.
  • SessionNotFound – The session relating to the SessionId could not be found.
  • PaymentFailed – The payment failed.
  • AwaitingSMSFromUser - The payment can proceed once the user has sent a message to the appropriate shortcode.
  • AwaitingPINValidation - The payment can proceed once the user submits a PIN for validation.
  • ValidatePINCallNotAllowedForThisPaymentCaptureMethod – This method should not be called for this PaymentCaptureMethod
  • CorrectPinCompletingBilling – The PIN entered is correct. Billing will now be completed by boxPAY.
  • InvalidPIN – The PIN entered is incorrect.
  • ServiceNotFound – No information was found relating to the ServiceId provided.
  • NotSubscribed – The user in question is not currently part of the subscription
  • SuccessfullyUnsubscribed – The user has been successfully removed from the subscription
  • AwaitingMSISDNEntry – The payment can proceed once the user enters the mobile number
  • OtherError – An unexpected error has occured
  • SubscriberNotFound – Details on the subscriber could not be found.

Appendix B – Subscription Status

The following enumeration is used to indicate the status of a payment in relation to a user’s subscription, i.e whether the payment session successfully subscribed the user or otherwise.

  • SUCCESS – The user was successfully subscribed
  • ALREADYSUBSCRIBED - The user is already subscribed to the service.
  • FAILED – An unexpected error occurred and the user was not subscribed to the service
  • NOTAPPLICABLE – Given for one-off (non-subscription) payments or for payment sessions that were not completed i.e. user did not complete payment