API Tokens

Guide of
Reference v6.4
About this guide
This provides general information about the API Token service and should be consulted by
technical personnel with experience in SOAP service integration, knowledge of data
exchange in JSON format, as well as the integration and implementation of AJAX elements
in WEB sites. The aspects necessary to perform an integration are covered here.

1
Contents
About this Guide ................................................................................................................................1
Operation ........................................................................................................................................3
Tokenization of a Credit Card ....................................................................................................3
Transaction Processing ...............................................................................................................3
Auxiliary Methods ......................................................................................................................4
Tokenization Widget .................................................................................................................. 4
Methods for Processing Transactions ............................................................................................ 6
leaves .......................................................................................................................................... 6
Rebill .......................................................................................................................................... 8
void ...........................................................................................................................................10
Credit ........................................................................................................................................ 10
PreAuthorization .......................................................................................................................11
Adjustment ................................................................................................................................13
Auxiliary Methods ........................................................................................................................14
GetTokenDetails .......................................................................................................................14
UpdateToken ............................................................................................................................ 14
GetTransactionResult ............................................................................................................... 15
Ping ...........................................................................................................................................16
Annex A ...........................................................................................................................................17
Response Codes – Token Operations ...........................................................................................17
Response Codes – Transactional Operations ...............................................................................17

two
Functioning
The main objective of the API Token is to expose the necessary functionalities to merchants, so
that they can implement mechanisms for capturing and storing sensitive data, such as cards and
cardholder information, in SIGMA's and Bank's PCI-certified premises. . The use of Tokens
instead of card data will be the primary way of executing transactions, also through services
exposed in this API.

Tokenization of a Credit Card

The tokenization process is done in one of two ways:
1. Using a Widget that must be embedded in the WEB page
2. Using the API's CreateToken method

The use of the Widget is required in those businesses that do not have PCI certification; creation
using the CreateToken method is reserved for PCI entities, since it implies a complete capture of
the cardholder's data on their websites.

This guide does not describe the use of the CreateToken method; To obtain formal
information about it, the business must present its AOC (Assessment of Compliance) issued by
the PCI certifying entity.

Transaction Processing
To process transactions it is required that the card to be used be tokenized. The API exposes the
following processing methods:
- Sale method ): used to execute a punctual debit with the interaction of the
cardholder. Example: debit for the purchase of an item or single payment of a service from
the WEB page
- Recurrence ( Rebill method ): used to execute debit transactions from a
automatic collection system, without cardholder interaction. Example: scheduled charges
from a recurring charges module or platform
- Void method ): used to reverse a transaction the same day the sale ( Sale ) or recurrence (
Rebill ) occurs. It does not require cardholder interaction and must be executed before the closing
time scheduled by the Bank.
- Credit method ): used to reverse a transaction after it has already been settled in the closing
process. No cardholder interaction required
- Pre-authorization ( PreAuthorization method ): used to make a reservation of money
which will then be adjusted (effective debit). Example: advance booking of a hotel stay,
which will then be effectively adjusted or debited when the guest checks out
- Adjustment method ): used to make a pre-authorization operation effective. If a pre-
authorization is not adjusted, the Bank may return the funds to the client after 5 days or more in
accordance with its internal policies, that is, the

3
 reservation and any attempt to make a debit would imply generating a sale or new pre-
authorization with its respective adjustment

Auxiliary Methods
The API has additional methods that allow managing the generated tokens, viewing the data related to
it in a secure way or knowing the result of the generated transactions:

- Token data ( GetTokenDetails method ): used to display the data of the card associated with
the token, without displaying data considered sensitive; Among these data are the masked PAN
number (eg 4111********1111), the expiration date and the name of the cardholder
- Update Token ( UpdateToken method ): used to update the expiration date and/or
cardholder of the card associated with the Token
- Result of a Transaction ( GetTransactionResult method ): used to obtain the result of a
transaction using the ID generated for it and the tracking number assigned by the merchant
- Ping method ): used to verify the availability of the service. Does not require input
parameters

Any other method not listed here, but visible in the WSDL schema of the service, cannot be
used without the technical support and authorization of the acquiring Bank .

Tokenization Widget
As an additional component to the API, the tokenization widget is included, which must be
embedded in the merchant's website to provide users with a secure way to capture the credit card.
1st Step: The AJAX code described below is embedded.

Code
$.ajax ({
"type": " GET ",
"url": " SANDBOX or PRODUCTION Widget URL ",
"data": {
"APIKey": " Key provided ",
"Token": " Token value when applicable ",
"Culture": " is "
},
"success": function ( jsonResponse ) {
$(" #creditcard-container ").html( jsonResponse );
}
});

4
 The APIKey is provided at the time of exchanging the integration data with the merchant,
since it is customized for each one in the test environment and in production.

- Sandbox Widget URL:

http://bacapicomponent.test.merchantprocess.net/UIComponent/CreditCard
- Production Widget URL:
https://bacgateway.merchantprocess.net/SecureComponent/UIComponent/CreditCard

2nd Step: the execution of the previous code will return a JSON response with the HTML form to
use to tokenize the card. This form must be rendered inside a container on the merchant's website.

Code

Captured JSON (displayed in AJAX code):

$(" #creditcard-container ").html( jsonResponse );

HTML container that will display the form:

<div id="creditcard-container"> <!-- THE FORM WILL BE DISPLAYED HERE --> </div>

3rd Step: if a token has been provided in the AJAX, the form will return the general the card
associated with it; Otherwise, the form will return without values, so that the data of a card can be
entered for its respective tokenization.

Callback functions must be used .

Code

Successfully tokenized card:

function SaveCreditCard_SuccessCallback( response )
{ console.log( response.TokenDetails.AccountToken
);
}

Failed Tokenization:
function SaveCreditCard_FailureCallback( response
) { console.log( response.ResponseCode );
console.log( response.ResponseDescription );
}

Cancellation in the form:

function SaveCreditCard_CancelCallback() {
console.log(" Cancel button pressed ");
}

To provide a visual guide to the customer, in case they want to see the card associated
with the token in any store interface, it is possible to capture and store the masked
name and number of the card, since both do not constitute sensitive data. It is also
recommended to store the value of AccountNumber .

5
 Code

Example of capturing Token, Account, Name and Masked Card:

var cardToken;
var accountNumber;
var cardholderName;
var associatedCard;

cardToken = response.TokenDetails.AccountToken ;
accountNumber = response.TokenDetails.AccountNumber ;
cardholderName = response.TokenDetails.CardHolderName ;
associatedCard = response.TokenDetails.CardNumber ;

The value of AccountNumber is required, if the use of the auxiliary method GetTokenDetails
is contemplated to obtain the data of the card associated with a token.

Methods for Processing Transactions

The detailed methods comply with the SOAP specification version 1.2; Once in production, the use
of TLS 1.2 and communication from a site protected by a certificate (HTTPS) is required.

- Sandbox API (without SSL):

http://tokenv2.test.merchantprocess.net/TokenWebService.asmx
- Sandbox API (with SSL): https://tokenv2test.merchantprocess.net/TokenWebService.asmx
- Production API: https://gateway.merchantprocess.net/tokenv2/TokenWebService.asmx

Comes out
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)

trade
accountToken Card token to use String (max 36)
accessCode Access Code of the String (max 10)

trade
merchantAccountNumber MID provided by the Bank String (max 10)
acquirer
terminalName TID provided by the Bank String (max 10)
acquirer
clientTracking internal reference ID of the String (max 50)

Trade
amount Transaction Amount Decimal (7,2)
currencyCode ISO 4217 numeric code of String (max 3)
the currency (840 = US
Dollar)
emailAddress Email of String (max 50)
cardholder
6
shippingName Name of the person who String (max 50)
receive the product or service
shippingDate Projected delivery date String
(MM/DD/YYYY format)
shippingAddress Delivery address String (max 50)
shippingCity delivery city String (max 50)
shippingState State or province of delivery String (max 50)
shippingCountry ISO 3166 code of the country of String (max 10)
delivery
shippingZipCode Address zip code String (max 50)
delivery
shippingPhoneNumber phone number of String (max 50)
contact at the address of
delivery
billingAddress Billing Address String (max 50)
billingCity billing city String (max 50)
billingState State or province of String (max 50)
billing
billingCountry ISO 3166 code of the country of String (max 10)
billing
billingZipCode Address zip code String (max 50)
billing
billingPhoneNumber phone number of String (max 50)
contact at the address of
billing
itemDetails Items Detail
associated with the transaction
code Product or service code String (max 100)
yam Product name or String (max 100)
service
description Product description or String (max 200)
service
quantity Sold units Integer
unitPrice Price by unit Decimal (7,2)
system Tracking Additional Reference ID String (max 50)
internal trade
additionalData Collection of values
trade-defined ( key
pair )
yam property name String (max 100)
value property value String (max 100)
cvv security code of the String (max 3)

card

7
Response / RESPONSE
Name Description Guy
transactionId transaction reference ID Integer
operationType Comes out Fixed value
tracking Value sent by the merchant in String
clientTracking
requestDate Date and time of the request DateTime
responseDate Response date and time DateTime
code Response code (see Code Table ) String (max 3)
binId Buyer BIN ID String (max 3)
authorizationNumber Authorization number (if the transaction is String (max 6)
approved)
processorId processor code Integer
description Response code description ( code ) String (max 100)
result response string String (max 100)
internalResponseCode Internal response code Integer

Rebill
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)
trade
accountToken Card token to use String (max 36)
accessCode Access Code of the String (max 10)
trade
merchantAccountNumber MID provided by the Bank String (max 10)
acquirer
terminalName TID provided by the Bank String (max 10)
acquirer
clientTracking internal reference ID of the String (max 50)
Trade
amount Transaction Amount Decimal (7,2)
currencyCode ISO 4217 numeric code of String (max 3)
the currency (840 = US Dollar)
emailAddress Email of String (max 50)
cardholder
shippingName Name of the person who String (max 50)
receive the product or service
shippingDate Projected delivery date String
(MM/DD/YYYY format)
shippingAddress Delivery address String (max 50)
shippingCity delivery city String (max 50)
shippingState State or province of delivery String (max 50)
ISO 3166 code of the country
shippingCountry of String (max 10)
delivery

8
shippingZipCode Address zip code String (max 50)
delivery
shippingPhoneNumber phone number of String (max 50)
contact at the address of
delivery
billingAddress Billing Address String (max 50)
billingCity billing city String (max 50)
billingState State or province of String (max 50)
billing
ISO 3166 code of the
billingCountry country of String (max 10)
billing
billingZipCode Address zip code String (max 50)
billing
billingPhoneNumber phone number of String (max 50)
contact at the address of
billing
itemDetails Detail of the articles
associated with the
transaction
code Product or service code String (max 100)
eit
he
yam Name of product r String (max 100)
service
eit
he
description Product description r String (max 200)
service
quantity Sold units Integer
unitPrice Price by unit Decimal (7,2)
systemTracking Additional Reference ID String (max 50)
internal trade
additionalData Collection of defined values
by trade (key pair)
yam property name String (max 100)
value property value String (max 100)
String (max
cvv security code of the 3)
card

Response / RESPONSE
Name Description Guy
transactionId transaction reference ID Integer
operationType Rebill Fixed value
tracking Value sent by the merchant in String
clientTracking
requestDate Date and time of the request DateTime
responseDate Response date and time DateTime
code Response code (see Code Table ) String (max 3)
binId Buyer BIN ID String (max 3)
authorizationNumber Authorization number (if the transaction is String (max 6)
approved)

9
processorId processor code Integer
description Response code description ( code ) String (max 100)
result response string String (max 100)
internalResponseCode Internal response code Integer

void
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)
trade
accessCode Access Code of the String (max 10)
trade
referenceId reference ID of the
transaction
clientTracking internal reference ID of the String (max 50)
Trade
systemTracking Additional Reference ID String (max 50)
internal trade
additionalData Collection of defined values
by trade (key pair)
yam property name String (max 100)
value property value String (max 100)

Response / RESPONSE
Name Description Guy
transactionId transaction reference ID Integer
operationType void Fixed value
tracking Value sent by the merchant in String
clientTracking
requestDate Date and time of the request DateTime
responseDate Response date and time DateTime
String (max
code Response code (see Code Table ) 3)
String (max
binId Buyer BIN ID 3)
String (max
authorizationNumber Authorization number (if the transaction is 6)
approved)
processorId processor code Integer
description Response code description ( code ) String (max 100)
result response string String (max 100)
internalResponseCode Internal response code Integer

Credit
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)
trade
10
accessCode Access Code of the String (max 10)
trade
referenceId reference ID of the
transaction
clientTracking internal reference ID of the String (max 50)
Trade
systemTracking Additional Reference ID String (max 50)
internal trade
amount Transaction amount Decimal (7,2)
additionalData Collection of defined values
by trade (key pair)
yam property name String (max 100)
value property value String (max 100)

Response / RESPONSE
Name Description Guy
transactionId transaction reference ID Integer
operationType Credit Fixed value
tracking Value sent by the merchant in String
clientTracking
requestDate Date and time of the request DateTime
responseDate Response date and time DateTime
String (max
code Response code (see Code Table ) 3)
String (max
binId Buyer BIN ID 3)
String (max
authorizationNumber Authorization number (if the transaction is 6)
approved)
processorId processor code Integer
description Response code description ( code ) String (max 100)
result response string String (max 100)
internalResponseCode Internal response code Integer

PreAuthorization
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)
trade
accountToken Card token to use String (max 36)
accessCode Access Code of the String (max 10)
trade
merchantAccountNumber MID provided by the Bank String (max 10)
acquirer
terminalName TID provided by the Bank String (max 10)
acquirer
clientTracking internal reference ID of the String (max 50)
Trade
eleven
amount Transaction Amount Decimal (7,2)
currencyCode ISO 4217 numeric code of String (max 3)
the currency (840 = US
Dollar)
emailAddress Email of String (max 50)
cardholder
shippingName Name of the person who String (max 50)
receive the product or service
shippingDate Projected delivery date String
(MM/DD/YYYY format)
shippingAddress Delivery address String (max 50)
shippingCity delivery city String (max 50)
shippingState State or province of delivery String (max 50)
ISO 3166 code of the country
shippingCountry of String (max 10)
delivery
shippingZipCode Address zip code String (max 50)
delivery
shippingPhoneNumber phone number of String (max 50)
contact at the address of
delivery
billingAddress Billing Address String (max 50)
billingCity billing city String (max 50)
billingState State or province of String (max 50)
billing
ISO 3166 code of the country
billingCountry of String (max 10)
billing
billingZipCode Address zip code String (max 50)
billing
billingPhoneNumber phone number of String (max 50)
contact at the address of
billing
itemDetails Detail of the articles
associated with the transaction
code Product or service code String (max 100)
eit
he
yam Name of product r String (max 100)
service
eit
he
description Description of product r String (max 200)
service
quantity Sold units Integer
unitPrice Price by unit Decimal (7,2)
systemTracking Additional Reference ID String (max 50)
internal trade
additionalData Collection of defined values
by trade (key pair)
yam property name String (max 100)
value property value String (max 100)

12
 String (max
cvv security code of the 3)
card

Response / RESPONSE
Name Description Guy
transactionId transaction reference ID Integer
operationType PreAuthorization Fixed value
tracking Value sent by the merchant in String
clientTracking
requestDate Date and time of the request DateTime
responseDate Response date and time DateTime
code Response code (see Code Table ) String (max 3)
binId Buyer BIN ID String (max 3)
authorizationNumber Authorization number (if the transaction is String (max 6)
approved)
processorId processor code Integer
description Response code description ( code ) String (max 100)
result response string String (max 100)
internalResponseCode Internal response code Integer

adjustment
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)
trade
accessCode Access Code of the String (max 10)
trade
referenceId reference ID of the String (max 10)
transaction
clientTracking internal reference ID of the String (max 50)
Trade
system Tracking Additional Reference ID String (max 50)
internal trade
amount Transaction amount Decimal (7,2)
additionalData Collection of defined values
by trade (key pair)
yam property name String (max 100)
value property value String (max 100)

Response / RESPONSE
Name Description Guy
transactionId transaction reference ID Integer
operationType adjustment Fixed value
tracking Value sent by the merchant in String
clientTracking

13
requestDate Date and time of the request DateTime
responseDate Response date and time DateTime
code Response code (see Code Table ) String (max 3)
binId Buyer BIN ID String (max 3)
authorizationNumber Authorization number (if the transaction is String (max 6)
approved)
processorId processor code Integer
description Response code description ( code ) String (max 100)
result response string String (max 100)
internalResponseCode Internal response code Integer

Auxiliary Methods
GetTokenDetails
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)
trade
accountNumber AccountNumber value String
returned by tokenizing the
card

Response / RESPONSE
Name Description Guy
responseCode Result code of the request (see String (max 3)
Code Table )
responseDescription Result Code Description String (max 100)
( responseCode )
accountToken Token sent in the request GUID (max 36)
accountNumber value of accountNumber sent in the String (max 100)
petition
cardholderName Cardholder name String (max 100)
cardNumber Masked card number (Example: String (max 16)
####********####)
expirationDate Card expiration date (format String
MMYY)

UpdateToken
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)
trade
accountToken Card token to use String (max 36)

14
expirationDate expiration date of the String
card (MMYY format)
cardholderName Cardholder name String (max 100)

Response / RESPONSE
Name Description Guy
responseCode Result code of the request (see String (max 3)
Code Table )
responseDescription Result Code Description String (max 100)
( responseCode )
accountToken Token sent in the request GUID (max 36)
accountNumber value of accountNumber sent in the String (max 100)
petition
cardholderName Cardholder name String (max 100)
cardNumber Masked card number (Example: String (max 16)
####********####)
expirationDate Card expiration date (format String
MMYY)

GetTransactionResult
Petition / REQUEST
Name Description Guy Required
API Key Unique key that identifies the String (max 100)
trade
accountNumber MID provided by the Bank String (max 10)

acquirer
clientTracking internal reference ID of the String (max 50)
Trade
transactionId reference ID of the String (max 10)
transaction
amount Transaction amount Decimal (7,2)
systemTracking Additional Reference ID String (max 50)
internal trade

Response / RESPONSE
Name Description Guy
transactionId transaction reference ID Integer
operationType Type of operation originally performed String (max 100)
( Sale , PreAuthorization , Adjustment , Credit
,
void )
clientTracking Merchant internal reference ID String (max 100)
sent on request
requestDate Date and time of the request DateTime
responseDate Response date and time DateTime
String (max
authorizationNumber Transaction authorization number 6)
fifteen
 responseCode Result code of the request (see String (max 3)
Code Table )
responseDescription Result Code Description String (max 100)
( responseCode )

Ping
The Ping operation consists of sending a request without input parameters, to verify the
availability of the API service. The expected result is an HTTP 200 code and the date/time in the
returned PingResult variable .

Code

Ejemplo de petición:
<x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<x:Header/>
<x:Body>
<tem:Ping></tem:Ping>
</x:Body>
</x:Envelope>

Respuesta:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<PingResponse xmlns="http://tempuri.org/">
<PingResult> 9/17/2021 1:20:39 PM </PingResult>
</PingResponse>
</soap:body>
</soap:Envelope>

The business is recommended to implement a verification mechanism based on this

method (minimum 10-minute cycles), to alert its customers preventively in the event
of communication or API access problems, as well as to temporarily pause any
transactional process until the service is restored.

16
Annex A
Response Codes – Token Operations
Code Description
T00 Success
T01 internal error
T02 Account / Token already exists
T03 Authorization failed
T04 Account / Token does not exist
T05 invalid input
T06 No transaction found
T07 updated token

These codes are returned in the responseCode field of the GetTokenDetails and UpdateToken
operations, as well as in the variable of the same name in the JSON response when the
Tokenization form (Widget) is executed.

Response Codes – Transactional Operations

Code Description
00 Approved transaction
B01 Call the Issuing Bank
B02 Call the Issuing Bank
B03 Invalid MID
B05 Not honored by the Issuing Bank
06 Call the Issuing Bank
eleven Approved transaction
B12 Invalid transaction
B13 Invalid amount
B14 Invalid card
fifteen Non-existent Issuer
17 Invalid Date
B19 Try again later. Processor Timeout
B21 Invalid Credit, the reference transaction does not exist
30 Format Error
31 Issuing Bank Not Allowed
39 Invalid transaction
B41 Hold Card
B43 Hold Card
B51 Insufficient funds
52 Invalid Account
53 Invalid Account
B54 Expired Card

17
B58 Invalid transaction
70 declined. Previously approved transaction
B75 Declined by the Issuing Bank
76 declined. There is no pre-authorized transaction
B78 transaction not found
81 Card is not Debit or Credit
82 There is no reference
B89 Error in TID
90 Service not available
91 Transmitter out of service
92 Invalid Issuer
94 duplicate transmission
B96 Call the Issuing Bank
ECB Processor Communication Error
BDB Database Error
BET Error in TID or BIN not allowed
BIA amount is invalid
BIT Invalid TID
BNA Processing Not Available
BNV Invalid transaction
BRR Processor Communication Error
BWE Processor Communication Error
A0 Exceeded Monthly Volume
N7 Declined due to failure in CVV2 security code
99 Timeout
100 Wrong request format
101 unauthorized transaction
102 Unauthorized MASTERCARD transaction
103 Transaction number is required
104 Card type is required
105 CVV is required
106 Currency code is required
107 Cardholder name is required
108 unauthorized credit
109 Unauthorized cancellation
110 Invalid Card Type. Only Visa and MasterCard are allowed
111 Invalid TID
112 invalid IP address
113 Delivery Address (Shipping) is required
114 Billing Address is required
116 Invalid Card Number
117 expired card
118 amount is invalid
119 The adjustment cannot be made, the pre-authorization is not found
122 Only the currency "US Dollar" is authorized. Use code 840
123 Merchant is not authorized to process
18
124 The transaction exceeded the allowed limit
125 Merchant exceeded the monthly amount of transactions
126 Merchant exceeded the maximum number of test transactions
127 Invalid Card Type
128 Merchant exceeded monthly transaction limit
129 Trade exceeded the daily amount of transactions
130 Trade exceeded daily transaction limit
131 Declined, chargeback previously reported for this card
132 Declined, card reported lost/stolen
133 Declined, withdrawal instruction found
134 Declined, invalid issuer instruction found
135 miscellaneous bug
136 Card previously declined today
137 Previously declined card, try a lower amount
138 Card exceeded daily limit
139 Declined, only 3 approved transactions allowed
140 Invalid or unexpected cardholder, please try the correct one
141 Previously restricted card
145 High risk of detected fraud
150 miscellaneous bug
230 Sum of the amounts of the items is not equal to the amount of the
transaction
231 Items required and not included in the transaction
232 Site IP required and not included
233 Telephone or Email required and not included
2. 3.
4 Invalid or disallowed item
235 Unauthorized recurring transaction
998 Unable to contact processor, please try again
999 Unable to contact processor, please try again

These codes are returned in the code or responseCode field of the Sale, Rebill,
Void, Credit, PreAuthorization, Adjustment, and GetTransactionResult.

19