Credit and Debit cards

Learn how to integrate your solution to process credit or debit card payments.

Info

The Request and Response shown in this article apply to both the Gateway and Payfac models. For the Gateway model, take into account the recommendations shown in this section.

Request parameters

You need to include specific fields for this payment method to work correctly. Check the Request parameters section for details on basic purchase parameters such as amount and currency.

Property	Type	Mandatory?	Description
`TrxToken`	`string`	Yes	The token that identifies the customer’s card. For more information about how to create the token, refer to Customers.
`TargetCountryISO`	`string`	Yes	Indicate the destination country.
`Installments`	`integer`	No	This parameter refers to the number of payments that a credit card purchase is divided into.
`Customer` → `Email`	`string`	Yes	Customer’s email.
`Customer` → `FirstName`	`string`	Yes	Customer’s first name.
`Customer` → `LastName`	`string`	Yes	Customer’s last name.
`Customer` → `DocumentTypeId`	`numeric`	No	Customer’s document type. Refer to the Document types table to see the possible values.
`Customer` → `DocNumber`	`string`	No	Customer’s Document Number.
`Customer` → `PhoneNumber`	`string`	Yes	Customer’s phone number.
`Customer` → `BillingAddress` → `Country`	`string`	Yes	Customer’s Country.
`Customer` → `BillingAddress` → `State`	`string`	Yes	Customer’s State.
`Customer` → `BillingAddress` → `City`	`string`	Yes	Customer’s City.
`Customer` → `BillingAddress` → `AddressDetail`	`string`	Yes	Customer’s Address Detail.
`Customer` → `BillingAddress` → `PostalCode`	`string`	No	Customer’s Postal Code. Postal code is mandatory for the United States and Canada.
`Customer` → `ShippingAddress` → `Country`	`string`	No	Country of the Shipping Address.
`Customer` → `ShippingAddress` → `State`	`string`	No	State of the Shipping Address.
`Customer` → `ShippingAddress` → `City`	`string`	No	City of the Shipping Address.
`Customer` → `ShippingAddress` → `AddressDetail`	`string`	No	Address Detail of the Shipping Address.
`Customer` → `ShippingAddress` → `PostalCode`	`string`	No	Postal Code of the Shipping Address.
`CustomerIP`	`string`	No	IP of the customer that uses the service.
`DataUY`	`object`	No	Specific data for Uruguay. In Uruguay, two laws promote electronic payment methods by refunding VAT points. Law 19,210 (Financial inclusion law) and 17,934 for gastronomic and related services govern these benefits, and the data presented in this object is necessary for correct usage. This parameter is required for the Gateway model.
`DataUY` → `IsFinalConsumer`	`boolean`	No	Indicates if the sale is performed to a final consumer. This parameter is required for the Gateway model.
`DataUY` → `Invoice`	`string`	No ^*	Invoice number associated with the sale. This parameter only accepts numeric characters.
`DataUY` → `TaxableAmount`	`number`	No ^*	Amount taxed by VAT.

Info

^* This parameter is mandatory when DataUY.IsFinalConsumer is true.
Remember that for the Anti-fraud system’s correct functioning, we suggest sending additional data described in the section Anti-fraud.

Request example

{
  "TrxToken": "OT__AJrM-jq7nqEZUiuiTpUzImdM_6Cp7rxT4jiYpVJ8SzQ_",
  "Capture": true,
  "Order": "20201229",
  "Amount": "10000",
  "Currency": "USD",
  "TargetCountryISO": "UY",
  "Installments": 1,
  "Customer": {
    "BillingAddress": {
      "Country": "Uruguay",
      "City": "Montevideo",
      "State": "Montevideo",
      "PostalCode": "150000",
      "AddressDetail": "Calle falsa 4567/Depto/Provincia"
    },
    "Email": "rserrano@mail.com",
    "DocNumber": "47666489",
    "DocumentTypeId": 2,
    "PhoneNumber": "0930000111",
    "FirstName": "Rodrigo",
    "LastName": "Serrano"
  }
}

Response parameters

For more information on the response parameters, please refer to the Response parameters section of the Purchase creation.

Response example

{
  "Response": {
    "PurchaseId": 1248284,
    "Created": "2023-09-29T15:34:10.012",
    "TrxToken": null,
    "Order": "20201229",
    "Transaction": {
      "TransactionID": 1267112,
      "Created": "2023-09-29T15:34:10.012",
      "AuthorizationDate": "",
      "TransactionStatusId": 1,
      "Status": "Approved",
      "ErrorCode": "0",
      "Description": "",
      "ApprovalCode": null,
      "Steps": [
        {
          "Step": "Generic External",
          "Created": "",
          "Status": null,
          "ResponseCode": "00",
          "ResponseMessage": "Authorization - Function performed error-free",
          "Error": "0",
          "AuthorizationCode": "586316",
          "UniqueID": null,
          "AcquirerResponseDetail": "{\"TransactionResult\":\"APPROVED\",\"ProcessorResponseCode\":\"00\",\"ProcessorResponseMessage\":\"Function performed error-free\",\"ApprovalCode\":\"Y:586316:4637904926:PPXX:5863160734\",\"OrderId\":\"A-79d7a01b-5b36-4326-b872-82c29f196ec0\",\"IpgTransactionId\":\"84637904926\",\"ProcessorApprovalCode\":\"586316\",\"ProcessorReceiptNumber\":\"0734\",\"ProcessorBatchNumber\":\"001\",\"ProcessorReferenceNumber\":\"586316586316\",\"ProcessorTraceNumber\":\"586316\"}"
        }
      ]
    },
    "Capture": true,
    "Amount": 10000,
    "OriginalAmount": 10000,
    "TaxableAmount": 0,
    "Tip": 0,
    "Installments": 1,
    "Currency": "USD",
    "Description": null,
    "Customer": {
      "CustomerId": 254952,
      "Created": "2023-09-29T15:34:05.713",
      "CommerceCustomerId": null,
      "Owner": "Anonymous",
      "Email": "rserrano@mail.com",
      "Enabled": true,
      "ShippingAddress": null,
      "BillingAddress": {
        "AddressId": 377785,
        "AddressType": 2,
        "Country": "Uruguay",
        "City": "Montevideo",
        "State": "Montevideo",
        "PostalCode": "150000",
        "AddressDetail": "Calle falsa 4567/Depto/Provincia"
      },
      "Plans": null,
      "AdditionalData": null,
      "PaymentProfiles": [
        {
          "PaymentProfileId": 259793,
          "PaymentMediaId": 2,
          "Created": "2023-09-29T15:34:05.713",
          "LastUpdate": null,
          "Brand": "MasterCard",
          "CardOwner": "Rodrigo Serrano",
          "Bin": null,
          "IssuerBank": null,
          "Installments": null,
          "Type": "CreditCard",
          "IdCommerceToken": 0,
          "Token": null,
          "Expiration": "202912",
          "Last4": "0008",
          "Enabled": null,
          "DocumentNumber": null,
          "DocumentTypeId": null,
          "ExternalValue": null,
          "AffinityGroup": null
        }
      ],
      "CaptureURL": null,
      "UniqueID": null,
      "URL": "https://api.stage.bamboopayment.com/Customer/254952",
      "FirstName": "Rodrigo",
      "LastName": "Serrano",
      "DocNumber": "47666489",
      "DocumentTypeId": 2,
      "PhoneNumber": "0930000111",
      "ExternalValue": null
    },
    "RefundList": null,
    "PlanID": null,
    "UniqueID": null,
    "AdditionalData": null,
    "CustomerUserAgent": null,
    "CustomerIP": null,
    "URL": "https://api.stage.bamboopayment.com/Purchase/1248284",
    "DataUY": {
      "IsFinalConsumer": false,
      "Invoice": null,
      "TaxableAmount": 0
    },
    "DataDO": {
      "Invoice": null,
      "Tax": 0
    },
    "Acquirer": {
      "AcquirerID": 73,
      "Name": "FiservIPG",
      "CommerceNumber": null
    },
    "CommerceAction": null,
    "PurchasePaymentProfileId": 259793,
    "LoyaltyPlan": null,
    "DeviceFingerprintId": null,
    "MetadataIn": null,
    "MetadataOut": null,
    "CrossBorderData": null,
    "CrossBorderDataResponse": null,
    "Redirection": null,
    "IsFirstRecurrentPurchase": false,
    "AntifraudData": {
      "AntifraudFingerprintId": null,
      "AntifraudMetadataIn": null
    },
    "PaymentMediaId": null,
    "PurchaseType": 1,
    "HasCvv": null,
    "TargetCountryISO": null
  },
  "Errors": []
}

Testing cards

When generating valid card data for testing, you must first establish which acquirer you want to test and what type of test you want to perform.

Determination of BIN

When setting up an acquirer, the card’s BIN (Bank Identification Number) is also created. This BIN should align with one of the BINs associated with the brands processed by the acquirer. For instance, if you are conducting an integration test with MasterCard, the BIN of the generated card should adhere to the following format: ^ 5 \ [1-5] \ [0-9]*

This format means it must start with the number 5; the second number must be between 1 and 5, then any other number is accepted. For example, the BIN to test can be 510000. The valid Bines in the system and their related acquirer are listed below.

BIN (format)	Brand	Notes
`^4\[0-9]*`	VISA	Any card that starts with `4`.
`^5\[1-5]\[0-9]*`	MasterCard	Any card that starts with `51` through `5`.
`^589892\|^542991`	OCA	Any card that starts with `589892` or `542991`.

Configured Behaviors for the Payfac model

The behavior of the response will depend on the amount sent. Use the following cards to simulate the different purchase statuses.

Brand	PAN	CVV	Expiration Date
Mastercard	`5165850000000008`	`123`	`12/29`
Visa	`4704550000000005`	`123`	`12/29`

Cards without CVV

Brand	PAN	Expiration Date
Mastercard Credit	`5101980000000000`	`12/29`
Mastercard Prepaid	`5599260000000006`	`12/29`
Visa Credit	`4103770000000006`	`12/29`
Visa Debit	`4213000000000005`	`12/29`
Visa International Credit	`4147960000000001`	`12/29`
Visa International Debit	`4345590000000006`	`12/29`

Behavior	Amount
Result: Rejected Error: The card can’t operate with installments.	UYU 1045,00
Result: Rejected Error: Expired card.	UYU 1046,00
Result: Rejected Error: Insufficient funds.	UYU 1051,00
Result: OK Approved	Less than or equal to UYU 1000,00 Greater than UYU 1061,00

Configured Behaviors for the Gateway model

The behavior of the response will depend on the termination of the card. Generate the card using the corresponding bin of the brand, and send the following last four digits according to the expected result.

Termination	Behavior
`0001`	Result: OK Approved.
`0002`	Result: Rejected Error: TR007 Error with some data of the payment method (card number, verification code or expiration date).
`0013`	Result: Rejected Error: TR012 Credit limit exceeded.

Special features for the Gateway model

You can make purchases in installments as long as the Issuing Bank has it enabled.
You can make purchases with Debit Cards as long as the Issuing Bank has it enabled
Visanet requires the inclusion of the CVV in the customer’s first purchase or the customer’s registration.
Once you make the registration and obtain the Commerce Token, it is not necessary to request the CVV in future transactions.
Fiserv requires you to send the CVV, even if you have the Commerce Token. You need to execute Verification Code Request Flow.
This modality is enabled by default. If you wish to deactivate it, you must negotiate with Fiserv and notify us.
Creditel and PassCard require that the purchase message include the cardholder’s document and type of document (fields Customer.DocumentTypeId and Customer.DocNumber).
PassCard requires you to send the CVV, even if you have the Commerce Token. Therefore, you need to execute Verification Code Request Flow.
When using OCAOneClick2 (OCA Multi-Acquiring), you need to include the IP address of the person making the purchase. To do this, you must send the CustomerIP parameter in the request.

Purchases using MasterCard through OCA

When using MasterCard, sending the device FingerPrint using the SetDeviceFingerPrint method is recommended.

Add this function to the script used for the checkout form (PWCheckOut) to generate and return the value used in the purchases.

In this example, we show how to invoke and obtain the result.

<script type="text/javascript">
    PWCheckout.SetDeviceFingerprint();
</script>

Then, include the token in the purchase creation according to the following scenarios.

For OneTimeToken, send the device FingerPrint you generate and the OT token.
For CommerceToken, there are two cases:
- For Recurring purchases (Without CVV), send the device FingerPrint you generate and the CT token. You can use an existing CT token or generate one.
- For Purchases with CVV, generating a DeviceFingerPrint is unnecessary since when the customer enters the CVV, the system sends the value generated when displaying the CVV request page. Then, the system generates a Purchase in the Pending state, and you need to redirect the customer to the URL returned in the actionUrl parameter where they enter the CVV.

Last modified June 24, 2024