Flex (E-Commerce Basic Gateway)

Owned by Víctor Macías
Last updated: Feb 20, 2024 by Bryan Diaz
8 min read

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://lancehorn.billpocket.dev/scops/

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

 

The production-enabled environment can be found at

  • https://lancehorn.billpocket.com/scops

 

Please also note:

  • All POST requests must be sent in JSON format.

  • All GET requests 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 later from our team.

1. Card tokenization

1.1 Store Card Data

Method: POST

Content-Type: application/json

Path: /card

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

Request format

{ "pan" : "5555555555555555", // Card Number to store "expDate" : "2012", // Card Expiration Date YYMM "apiKey" : "myAPIKey" // Your API Access Key }

Response Format (HTTP 200: OK)

{ "status" : 1, // 1=Success, Else=Error "message" : "An error has ocurred", // Error description when an error is returned "cardToken" : "myCardToken5555", // Unique identifier for the stored card "maskedPAN" : "555555******5555" // Masked Card Number }

 

Request Error (HTTP 400: Bad Request)

If a malformed JSON is supplied, or has unexpected fields

 

1.2 Get Tokenized Card Details

Method: GET

URL: /card/<cardToken>?

Query: api_key=<api_key>

Get tokenization status for a given token.

URL Parameters

/card/myCardToken5555?api_key=myApiKey <cardToken> -> String. Card Token to check <api_key> -> String. Your API access key

Response Format (HTTP 200: OK)

Request Error (HTTP 400: Bad Request)

If a malformed URL is supplied or has unexpected fields

 

2. Authorization

2.1 Authorization Request with Token

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.

2.1.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 ’

2.1.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”.

2.1.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

2.1.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.

2.1.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

2.1.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, 12, 18 and 24

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

2.1.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

Not supported by AMEX cards: AMEX doesn’t support recurring transactions. However if it is required to send an AMEX transaction without the 4dbc it could be achieved by a tokenized card authorization request (2.2).

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

  • recurringCheckIn

Not supported by AMEX cards

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

2.1.7 REFERENCE

This fields is an internal identifier of the transaction in your systems, for tracking purposes in case you are using the “Authorization Webhook Spec“(See docs)

Response Format Success: HTTP 200 (OK)

Request Error (HTTP 400: Bad Request)

If a malformed JSON is supplied or has unexpected fields.

2.2 AMEX Authorization request without 4DBC request (only for tokenized cards)

There is a combination of fields that can be sent in the token authorization request to get an AMEX authorization without 4DBC. AMEX validates card holder addresses, postal codes, and phone numbers to authorize the transaction. So they should be as accurate as possible. Example:

Where AMEX fields are:

  • amexCustAddress (String) Cardholder Billing Address (Max length: 20)

  • amexCustFirstName (String) Cardholder First Name (Max length: 15)

  • amexCustLastName (String) Cardholder Last Name (Max length: 30)

  • amexCustEmailAddr (String) Cardholder Email Address (Max length: 60)

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

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

  • amexCustIdPhoneNbr (String) Cardholder Phone Number (Max length: 10)

  • amexCustIPAddr (String) Customer IP Address (Max length: 15)

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

  • amexMerSKUNbr (String) Merchant SKU Number (Max length: 15)

2.3 Special recurring transactions for tokenized cards (development)

URL: /txn/recurring

Not supported by AMEX cards

It is an extension to the functionality offered by /txn since it additionally supports expired cards by automatically setting current month number + 1 in case the card is expired, otherwise, it behaves the same as /txn

2.4 Authorization Request (no token)

Method: POST

Content-Type: application/json

URL: /txn

Process a sale transaction, providing the credit card and transaction details

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

Response Format Success: HTTP 200 (OK)

Request Error (HTTP 400: Bad Request)

If a malformed JSON is supplied or has unexpected fields.

2.5 Special recurring transactions for NON tokenized cards (development)

URL: /txn/recurring

Not supported by AMEX cards

It is an extension to the functionality offered by /txn since it additionally supports expired cards by automatically setting the current month number + 1 in case the card is expired, otherwise, it behaves the same as /txn

2.6 Checkout/Refund Request

Method: POST

Content-Type: application/json

Refund URL: /txn/refund

Checkout URL: /txn/checkout

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

Request Format

 

NOTE: For partial refunds or checkouts, an amount less than the original transaction must be sent. If the amount field is sent as null, then a full refund or checkout will be executed. The amount field is required.

 

Below you can find the amount of days available to perform the corresponding check-out operation

 

20 days - Credit and debit cards

 

If you don't make the check-out process within that time, the funds retained will be released by the issuing bank back to the cardholder.

Finally, no fund transfer is performed until you complete a check-out request.

 

Response Format Success: HTTP 200 (OK)

 

 

Request Error (HTTP 400: Bad Request)

 

If a malformed JSON is supplied or has unexpected fields.

 

2.7 Check transaction details

Method: GET

URL: /txn/<opId>?

Query: api_key=<api_key>

Get details from the specified transaction.

URL Parameters

Response Format Success: HTTP 200 (OK)

Request Error (HTTP 400: Bad Request)

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

© Billpocket, 2018