Loyalty plans

Learn how to integrate your solution to process payments using Loyalty plans such as SoySantander or OCA Metros.

SoySantander

SoySantander allows customers to use points to pay the total or partial purchase amount. Using our API, you can create purchases and consult the number of points of a customer.

Token request

The first step is to get a valid token to perform the transaction. If the purchase is mixed, get the token from the card as explained in Customers. Otherwise, invoke the method GetLoyaltyToken of the PWCheckout library.

Property	Type	Mandatory?	Description
`loyaltyPlanId`	`numeric`	Yes	Identifier of the Loyalty plan.
`LoyaltyPlanUserIdentification`	`string`	Yes	User identifier in the Loyalty Plan. Santander generates this value using an algorithm, and they indicate it to you.
`email`	`string`	Yes	E-mail address of the customer.

Example:

<script type=”text/javascript”>
    PWCheckout.GetLoyaltyToken(1, "ExampleLoyaltyPlanUserId", "email@bank.com");
</script>

Purchases with SoySantander points

Once you have the token associated with the Loyalty Plan, Create a Purchase using it. Furthermore, include the LoyaltyPlan object with the number of points to redeem and the user identifier of the Loyalty Plan.

Property	Type	Mandatory?	Description
`TrxToken`	`string`	Yes	Token generated as explained in Token request.
`Order`	`string`	Yes	Order number of the purchase.
`Amount`	`number`	No	Amount of the purchase. Send this parameter for Mixed purchases (Points + a card). Otherwise, discard it. If you must include decimals in the amount, concatenate the decimal places without de decimal point. Example `12,25` > `1225`.
`Currency`	`string`	No	Currency of the purchase, according to ISO-4217. Find the possible values in the Currencies table. Send this parameter for Mixed purchases (Points + a card). Otherwise, discard it.
`Capture`	`boolean`	Yes	Send `true` in this parameter as the Loyalty plan purchases don’t support Pre-authorization.
`LoyaltyPlan` → `LoyaltyPlanId`	`numeric`	Yes	Identifier of the Loyalty plan.
`LoyaltyPlan` → `Amount`	`numeric`	Yes	Total of points to redeem.
`LoyaltyPlan` → `LoyaltyPlanUserIdentification`	`string`	Yes	User identifier in the Loyalty Plan. Santander generates this value using an algorithm, and they indicate it to you.

Info

The outcome of a mixed purchase depends on processing points and cards. If the acquirer rejects either of these processes, the entire purchase will also be rejected.

Request example

{
    "TrxToken":"OT_02_kYv0qTHckRiZ4wjCz5NguZRuwFLSIrQc4jiYpVJ8SzQ_", 
    "Order":"17030613595101621fb",
    "Capture":true,
    "LoyaltyPlan": {
           "LoyaltyPlanId":1,
           "Amount":100,
           "LoyaltyPlanUserIdentification": "eyd1c2VyaWQnOid0ZXN0QGRvbWFpbi5jb20nfQ==",
     }
}

Request example for mixed purchases

{
    "TrxToken":"OT_01_kYv0qTHckRiZ4wjCz5NguZRuwFLSIrQc4jiYpVJ8SzQ_", 
    "Order":"17030613595101621fb",
    "Amount": 123400, 
    "Currency":"UYU", 
    "Capture":true,
    "LoyaltyPlan": {
           "LoyaltyPlanId":1,
           "Amount":120,
           "LoyaltyPlanUserIdentification": "eyd1c2VyaWQnOid0ZXN0QGRvbWFpbi5jb20nfQ==",
     }
}

Consulting the number of points

To get the number of points available for a user, create a POST request to the following URL:

Production: https://api.bamboopayment.com/v1/api/LoyaltyPlan/{{LoyaltyPlan-ID}}/Balance
Stage: https://api.stage.bamboopayment.com/v1/api/LoyaltyPlan/{{LoyaltyPlan-ID}}/Balance

Where {{LoyaltyPlan-ID}} is the identifier of the Loyalty plan you want to consult. Furthermore, recall the usage of the Authentication as explained in Purchase operations.

Request parameters

Include the following parameters in the request.

Property	Type	Mandatory?	Description
`LoyaltyPlanId`	`numeric`	Yes	Identifier of the Loyalty plan.
`LoyaltyPlanUserIdentification`	`string`	Yes	User identifier in the Loyalty Plan. Santander generates this value using an algorithm, and they indicate it to you.
`TrxToken`	`string`	Yes	Token generated as explained in Token request.

Request example

{
  "LoyaltyPlanId": 1,
  "LoyaltyPlanUserIdentification": "eyJDbGllbnRUb2tlbiI6Ik9UX19yR1NFV0VUeV9yNDhBbS10bjdIdUIzWlFIVTd4MkJXbzRqaVlwVko4U3pRXyIsIlR5cGUiOiXXXXXXXXXX",
  "TrxToken": "OT__ue2pwtim4aywkM6SWFI3g8YdDsuhfC2i4jiYpVJ8SzQ_"
}

Response example

The Balance parameter in the response contains the points available to the user.

{
  "LoyaltyPlanBalance": {
    "ResponseCode": 0,
    "LoyaltyPlanId": 1,
    "Name": "Soy Santander",
    "LoyaltyPlanUserIdentification": "eyJDbGllbnRUb2tlbiI6Ik9UX19yR1NFV0VUeV9yNDhBbS10bjdIdUIzWlFIVTd4MkJXbzRqaVlwVko4U3pRXyIsIlR5cGUiOiXXXXXXXXXX",
    "Balance": 6954.0
  },
  "Errors": []
}

OCA Metros

OCA Metros is the loyalty plan OCA offers that allows customers to purchase using points and a card.

Considerations

When using OCA Metros, consider the following.

Refunds with OCA Metros must be total.
There are no pre-authorizations with OCA Metros.
Send the Points as numbers without decimals.
You can use OCA Metros only for MasterCard cards issued by OCA.

Purchases with OCA Metros

To create a purchase with Metros, include the OCAMetros parameter with the number of OCA Metros to redeem in the MetadataIn structure for the Purchase object. For more information about creating a Purchase, refer Credit and Debit cards.

The following example demonstrates how to use it and obtain the result:

{
	"TrxToken":"OT__Hj3J8kzK1CFSv4SyMqSyUkc1WfJpjJf84jiYpVJ8SzQ_",
	"Capture": true,
	"MetadataIn" : {
        "OCAMetros": "12"
    },
	"Order": "20201229",
	"Amount":"1000",
	"CustomerIP": "127.0.0.1",
	"Currency":"USD",
	"Installments": 1
}

Last modified December 30, 2024