Billpocket

e-Commerce API

Billpocket Dev Ops

[email protected]

October, 2017

Stored Card API

Abstract
This document describes Billpocket’s API for online transaction processing, which allows 3rd-Party
entities to securely process transactions by providing details about the card and the amount to be
charged.

For demo purposes, you can use the following endpoint:

https://test.bpckt.com/scops

which doesn’t actually processes the transaction but provides correct responses to the requests.

All POST requests must be sent in JSON format.

All GET request will feature the parameters in the URL query section.
All response payloads are in JSON format, except when noted.

You will receive your production-environment API Key and endpoints later from out team.

Stored Card API

1. Card Tokenization
1.1 Store Card Data
Method=POST | Content-Type=application/json | URL=/card

Store card details on our server. Response will contain a unique identifier or “token" for the given card.

Request Format

Field Description Type

pan Credit / Debit card number String

cvv2 Card's Security Code (or Amex’s 4DBC) String

expDate Card’s Expiration Date (YYMM) String

apiKey Your API access key String

Response Format (HTTP 200: OK)

Field Description Type

1: Success
status integer
Negative Number: Error

message Error description when an error is returned String

cardToken Unique identifier for the stored card String

maskedPAN Masked Card Number String

Request Error (HTTP 400: Bad Request)

If a malformed JSON is supplied, or has unexpected fields.

Stored Card API

1.2 Get Tokenized Card Details
Method=GET | URL=/card/<cardToken>?api_key=<apiKey>

Get tokenization status for a given token.

URL Parameters

Field Description Type

<cardToken> Card Token to check String

<api_key> Your API access key String

Response Format (HTTP 200: OK)

Field Description Type

status 1: Success integer

message "Card [does/does not] exist " String

maskedPAN Masked Card Number (if card exists) String

Request Error (HTTP 400: Bad Request)

If a malformed JSON is supplied, or has unexpected fields.

Stored Card API

1.3 Authorization Request
Method=POST | Content-Type=application/json | URL=/txn

Request a transaction authorization for a tokenized card.

For American Express cards, the fields prefixed with “amex" are mandatory, otherwise they’re ignored.

Request Format

Field Description Type

apiKey Your API access key String

cardToken Unique identifier for the stored card String

amount Amount to be charged double

txnType Optional, see notes String

contractNumber Mandatory for Recurring Transactions String

paymentPlan Payment Plan indicator int

amexCustPostalCode Cardholder Billing Postal Code (Max length: 9) String

amexCustAddress Cardholder Billing Address (Max length: 20) String

amexCustFirstName Cardholder First Name (Max length: 15) String

amexCustLastName Cardholder Last Name (Max length: 30) String

amexCustEmailAddress Cardholder Email Address (Max length: 60) String

amexCustHostServerNm Customer Host Server Name (Max length: 60) String

amexCustBrowserTypDescTxt Customer HTTP Browser Type (Max length: 60) String

amexShipToCtryCd Country code (default: MX ’484’, Max length: 3) String

amexShipMthdCd Shipment method code (default ’02’, Max length, 2) String

amexMerSKUNbr Merchant SKU Number (Max length: 15) String

amexCustIPAddr Customer IP Address (Max length: 15) String

amexCustIdPhoneNbr Cardholder Phone Number (Max length: 10) String

amexCallTypId Call Type ID (Max length: 2) String

Stored Card API

1.2.1 CUSTOMER HTTP BROWSER TYPE
This data element contains the Customer’s HTTP Browser Type. i. e.: ’Mozilla/5.0 (Windows NT 10.0;
WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36 ’

1.2.2 COUNTRY CODE (ASSUMED 484 [MÉXICO] IF NOT SUPPLIED)

This data element contains the three-digit, numeric, Ship-to Country Code. For example, the country
code for a ship-to address in the USA is “840”.

1.2.3 SHIPMENT METHOD CODE (ASSUMED 02 IF NOT SUPPLIED)

This data element contains the two-character, Shipping Method Code (a.k.a., shipment-type code).
Valid values include:
• 01 = Same day
• 02 = Overnight / Next Day
• 03 = Priority, 2-3 days
• 04 = Ground, 4 or more days
• 05 = Electronic Delivery
• 06 = Ship-to Store
• 07 = RFU

1.2.4 MERCHANT SKU NUMBER

This data element contains the Merchant SKU Number, which is the product Stock Keeping Unit
inventory reference number of the product associated with this transaction. For multiple items, enter
the SKU for the single, most expensive item.

1.2.4 CALL TYPE ID (ASSUMED 61 IF NOT SUPPLIED)

This data element contains the Call Type ID (a.k.a., Customer II Digits), which are the phone company-
provided, “ANI ii” (Automatic Number Identification, Information Identifier) coding digits associated
with the Customer Identification Phone Number (a.k.a., Customer ANI) in sub-element
CustIdPhoneNbr. Typical values include:
• 24-25 = Toll free
• 27 = Payphone
• 61-63 = Cellular

1.2.5 PAYMENT PLANS

To process deferred-installments transactions you must supply the deferred payments plan as an
integer in the field “paymentPlan”

Valid values for this field are: 3, 6, 9 and 12

If this field is supplied, you must not populate the field “txnType”.

Stored Card API

1.2.6 TRANSACTION TYPES
Valid values for the field “txnType" include:

• checkIn
You must not supply the fields “contractNumber" nor “paymentPlan" if you indicate this value.

• recurring
You must supply the field “contractNumber" and must not supply a “paymentPlan" if you indicate this
value.

• recurringCheckIn
You must supply the field “contractNumber" and must not supply a “paymentPlan" if you indicate this
value.

Response Format
Success: HTTP 200 (OK)

Field Description Type

1: Success
status integer
Negative Number: Error

message Error description: Error String

opId Unique identifier for the processed transaction integer

txnISOCode ISO Code of the transaction response String

authNumber Transaction’s Authorization Number: Success String

ticketURL E-ticket Unique Identifier: Success String

amount Transaction's Authorized Amount double

maskedPAN Masked Card Number used for this transaction String

dateTime Timestamp for this operation (Unix Epoch, milis) long

Request Error (HTTP 400: Bad Request)

If a malformed JSON is supplied, or has unexpected fields.

Stored Card API

2. Non-Tokenized Card Operations
2.1 Authorization Request
Method=POST | Content-Type=application/json | URL=/txn
Process a sale transaction, providing the credit card and transaction details.
Please do note all the “amex”-prefixed fields from section 1.2 also apply to this endpoint

Request Format
Field Description Type

cardReq Card's details Compound

amount Amount to be charged double

apiKey Your API access key String

paymentPlan As detailed in section 1.2.5 int

amexOptFields Amex Optional Fields as detailed in section 1.2 of this document

Card Details Format (cardReq)

Field Description Type

pan Credit / Debit Card Number String

expDate Card’s Expiration Date (YYMM) String

cvv2 Card's Security Code (or Amex’s 4DBC) String

Response Format (HTTP 200: OK)

Field Description Type

1: Success
status integer
Negative Number: Error

message Error description: Error String

opId Unique identifier for the processed transaction integer

txnISOCode ISO Code of the transaction response String

authNumber Transaction’s Authorization Number: Success String

ticketURL E-ticket Unique Identifier: Success String

amount Transaction's Authorized Amount double

maskedPAN Masked Card Number used for this transaction String

dateTime Timestamp for this operation (Unix Epoch, milis) long

Request Error (HTTP 400: Bad Request)

If a malformed JSON is supplied, or has unexpected fields.
Stored Card API
2.2 Refund Request
Method=POST | Content-Type=application/json | URL=/txn/refund

Process a full refund por a previously approved transaction. Note that you can refund transactions
processed with tokenized or not-tokenized cards with this endpoint.

Request Format

Field Description Type

apiKey Your API access key String

opId Unique identifier of the transaction to query integer

Response Format (HTTP 200: OK)

Field Description Type

status 1: Success integer

message Depends on transaction details String

opId Unique identifier for the processed refund integer

txnISOCode ISO Code of the transaction response String

maskedPAN Masked Card Number used for this transaction String

dateTime Timestamp for this operation (Unix Epoch, milis) long

Request Error (HTTP 400: Bad Request)

If a malformed JSON is supplied, or has unexpected fields.

Stored Card API

2.3 Check transaction details
Method=GET | URL Format=txn/<opId>?api_key=<api_key>

Get details from the specified transaction.

Request Format

Field Description Type

opId Unique identifier for the processed transaction integer

Your API access key (query part of the request)

api_key String
txn/123456?api_key=myAwesomeAPIKey

Response Format (HTTP 200: OK)

Field Description Type

status 1: Success integer

message Depends on transaction details String

opId Unique identifier for the processed refund integer

txnISOCode ISO Code of the transaction response String

maskedPAN Masked Card Number used for this transaction String

dateTime Timestamp for this operation (Unix Epoch, milis) long

Request Error (HTTP 400: Bad Request

If a malformed JSON is supplied, or has unexpected fields.

Stored Card API