General

The use of gift cards and gift certificates as online payment method brings additional consequences. After all, the customer is now able to combine the gift card with another payment source, such as another gift card or iDEAL payment. While this provides the customer with the added bonus of extra payment options, the Payment Engine has to check at order level if full payment has been received. And because this involves multiple steps, there are many chances for things to go wrong. Partial payment, duplicate payments and uncompleted payments with an unknown status – Buckaroo’s Payment Engine has all these options covered.

Work Flow

A giftcard payment is initiated by sending a giftcard request to a BPE transaction gateway. The gateway processes the request and sends a response to the merchant. Additionally, a transaction push is sent to the merchant as well (Both contain the current status of the transaction).

Testing

For your convenience a test gift card is available that never expires or becomes fully consumed. The following test gift card can be used for this (the gift card code length is 19 digits, consisting of 18 zeroes, and a single one at the end):

0000000000000000001

Since you have to enter the pin of a gift card in the normal gift card payment flow, the entered pin is taken as being the value of this test gift card (in cents). This allows you to test partial payments and full consumption of a gift card.

To test a partial payment, enter a gift card pin value that is less than the requested payment amount in cents. This will start the partial payment flow.

Partial payments

 A payment done with a gift card can result in a partial payment. If the gift card does not contain enough money to fully pay for the requested amount, the gift card will be fully consumed and the customer will be asked to pay the remainder of the open amount. On gateways where the customer has been sent along, the payment engine will do this automatically. On gateways where the payment flow if handled by the merchant website, the merchant will need to do this. For more information on partial payments, please refer to the partial payment manual.

Servicecodes and actions

Each gift card has its own service code; you can find them at: http://support.buckaroo.nl/index.php/Service_giftcard

If you wish to use a giftcard that's not in the current selection, then you can submit it (up to 3 max) to info@buckaroo.nl. Once we configured your card in our system, you will be able to use it by providing service code customgiftcard/customgiftcard2/customgiftcard3 (you will be notified of the right service code).

The Giftcard service supports the following actions: Pay, Refund.

Pay

The pay action is the default action for the gift card service. The action is used to perform a gift card payment.

View in playground

Request


JSON gateway request

FashionChequeCardNumber

Required if the giftcard is processed by FashionCheque. The number as displayed on the actual fashion cheque card.

IntersolveCardnumber

Required if the giftcard is processed by Intersolve. The number as displayed on the InterSolve card.

IntersolvePIN

Required if the giftcard is processed by FashionCheque. The Personal Identification Number of the card.

TCSCardnumber

Required if the giftcard is processed by TCS. The number as displayed on the TCS card.

TCSValidationCode

Required if the giftcard is processed by TCS. The Personal Identification Number of the card.

JSON

copy
{
   "Currency": "EUR",
   "AmountDebit": 10,
   "Invoice": "testinvoice 123",
   "Services": {
      "ServiceList": [
         {
            "Name": "boekenbon",
            "Action": "Pay",
            "Parameters": [
               {
                  "Name": "IntersolveCardnumber",
                  "Value": "0000000000000000001"
               },
               {
                  "Name": "IntersolvePin",
                  "Value": "100"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

If the giftcard has sufficient balance to cover the full transaction amount, the payment can be completed with one giftcard transaction. The gateway response will return status code 190 (succes) with no further required action. However, if the balance does not cover the full amount and there is a remaining amount to be paid, the gateway response will provide a redirect URL to give the customer the opportunity to complete the payment on our checkout page. The payment will then consist of multiple partial payments. For more information, see the Partial Payments section.

JSON

copy
{
   "Key": "C11C13902A0848FCA1DA17C10332XXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2019-03-23T00:18:27"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "boekenbon",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 10,
   "TransactionType": "V238",
   "MutationType": 2,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": null,
   "PayerHash": null,
   "PaymentKey": "D450A4D7E25A49D3A5E9E643D6F2XXXX"
}

Push


JSON push response

JSON

copy
{
   "Transaction": {
      "Key": "901745AE6B4643C6837497C513D2xxxx",
      "Invoice": "testinvoice 123",
      "ServiceCode": "boekenbon",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": {
            "Code": "S003",
            "Description": "A partial payment of EUR 1 was successfully performed on a requested amount of EUR 10.00."
         },
         "DateTime": "2019-03-22T23:28:13"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountDebit": 1,
      "TransactionType": "V238",
      "Services": null,
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 2,
      "RelatedTransactions": [
         {
            "RelationType": "partialpayment",
            "RelatedTransactionKey": "40591C0E384A40AC8FF5C5D1C6A0xxxx"
         }
      ],
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": null,
      "PayerHash": null,
      "PaymentKey": "B14054AF06FA4997B98450C696D7xxxx"
   }
}

Refund

To refund a successful giftcard transaction, use the action Refund.

View in playground

Request


JSON gateway request

originaltransaction
Required

Transaction key of the original transaction that needs to be refunded. Please note: This is a basic request variable, not a service specific variable.

JSON

copy
{
   "Currency": "EUR",
   "AmountCredit": 1,
   "Invoice": "testinvoice 123",
   "OriginalTransactionKey": "901745AE6B4643C6837497C513D2xxxx",
   "Services": {
      "ServiceList": [
         {
            "Name": "boekenbon",
            "Action": "Refund"
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "62AB2EF2C17F42A1A79DC42CD552xxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2019-03-22T23:34:18"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "boekenbon",
   "IsTest": true,
   "Currency": "EUR",
   "AmountCredit": 1,
   "TransactionType": "V239",
   "MutationType": 2,
   "RelatedTransactions": [
      {
         "RelationType": "refund",
         "RelatedTransactionKey": "901745AE6B4643C6837497C513D2xxxx"
      }
   ],
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": null,
   "PayerHash": null,
   "PaymentKey": "B93B33C25C1840A9AF19DC609CF7xxxx"
}

Push


JSON push response

JSON

copy
{
   "Transaction": {
      "Key": "62AB2EF2C17F42A1A79DC42CD552xxxx",
      "Invoice": "testinvoice 123",
      "ServiceCode": "boekenbon",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": null,
         "DateTime": "2019-03-22T23:34:18"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountCredit": 1,
      "TransactionType": "V239",
      "Services": null,
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 2,
      "RelatedTransactions": [
         {
            "RelationType": "refund",
            "RelatedTransactionKey": "901745AE6B4643C6837497C513D2xxxx"
         }
      ],
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": null,
      "PayerHash": null,
      "PaymentKey": null
   }
}