General

A consumer starts a transaction. The merchant can choose if he/she wants to redirect the consumer to the Buckaroo checkout page or he/she will ask the required fields so that the consumer can stay on the merchants’ website. The required information will be sent to Buckaroo and Buckaroo checks the balance on the Buckaroovoucher. Buckaroo will check if the total amount that should be paid by the consumer is paid. A push will be sent to the merchant, it doesn’t matter if the total amount is paid. Also with a partial payment a push will be sent to the merchant. If it was a partial payment, a group transaction will be made in the Buckaroo Payment Engine. The customer will be able to pay the remaining amount. For every partial payment a push is also sent to the merchant.

Servicecodes and actions

The Buckaroo Voucher service uses the service code: buckaroovoucher

The Buckaroo Voucher service supports the following actions: Pay, Refund, GetBalance, CreateApplication

Pay

The Pay action is the default action. The action is used to perform a single payment with the Buckaroo Voucher.

View in playground

Request


JSON gateway request

VoucherCode
Required

VoucherCode of an active voucher

JSON

copy
{
  "Currency": "EUR",
  "AmountDebit": 10.00,
  "Invoice": "testinvoice 123",
  "Services": {
    "ServiceList": [
      {
        "Name": "buckaroovoucher",
        "Action": "Pay",
        "Parameters": [
          {
            "Name": "vouchercode",
            "Value": "WP6W-XXXX-XXXX-56T7"
          }
        ]
      }
    ]
  }
}

Response


JSON gateway response

JSON

copy
{
  "Key": "3171784167F8478C803090XXXXXXXXXX",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2020-06-04T09:51:51"
  },
  "RequiredAction": null,
  "Services": [
    {
      "Name": "buckaroovoucher",
      "Action": null,
      "Parameters": [
        {
          "Name": "VoucherCode",
          "Value": "WP6W-XXXX-XXXX-56T7"
        }
      ]
    }
  ],
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "Invoice": "testinvoice 123",
  "ServiceCode": "buckaroovoucher",
  "IsTest": true,
  "Currency": "EUR",
  "AmountDebit": 10,
  "TransactionType": "V800",
  "MutationType": 2,
  "RelatedTransactions": null,
  "ConsumerMessage": null,
  "Order": null,
  "IssuingCountry": null,
  "StartRecurrent": false,
  "Recurring": false,
  "CustomerName": null,
  "PayerHash": null,
  "PaymentKey": "D847D4B2EA8043EC90D441XXXXXXXXXX"
}

Push


JSON push response

JSON

copy
{
  "Transaction":{
    "Key":"3171784167F8478C803090XXXXXXXXXX",
    "Invoice":"testinvoice 123",
    "ServiceCode":"buckaroovoucher",
    "Status":{
      "Code":{
        "Code":190,
        "Description":"Success"
      },
      "SubCode":{
        "Code":"S001",
        "Description":"Transaction successfully processed"
      },
      "DateTime":"2020-06-04T09:51:51"
    },
    "IsTest":true,
    "Order":null,
    "Currency":"EUR",
    "AmountDebit":10.00,
    "TransactionType":"V800",
    "Services":[
      {
        "Name":"buckaroovoucher",
        "Action":null,
        "Parameters":[
          {
            "Name":"VoucherCode",
            "Value":"WP6W-XXXX-XXXX-56T7"
          }
        ],
        "VersionAsProperty":1
      }
    ],
    "CustomParameters":null,
    "AdditionalParameters":null,
    "MutationType":2,
    "RelatedTransactions":null,
    "IsCancelable":false,
    "IssuingCountry":null,
    "StartRecurrent":false,
    "Recurring":false,
    "CustomerName":null,
    "PayerHash":null,
    "PaymentKey":"D847D4B2EA8043EC90D441XXXXXXXXXX"
  }
}

Refund

The Refund action can be used to perform a refund on an earlier voucher transaction. There is no customer interaction needed to do this.

View in playground

Request


JSON gateway request

originaltransaction
Required

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

JSON

copy
{
  "Currency": "EUR",
  "AmountCredit": 10.00,
  "Invoice": "testinvoice 123",
  "OriginalTransactionKey": "3171784167F8478C803090XXXXXXXXXX",
  "Services": {
    "ServiceList": [
      {
        "Name": "buckaroovoucher",
        "Action": "Refund"
      }
    ]
  }
}

Response


JSON gateway response

JSON

copy
{
  "Key": "A419347FFC534AE3B34256XXXXXXXXXX",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2020-06-04T09:59:30"
  },
  "RequiredAction": null,
  "Services": null,
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "Invoice": "testinvoice 123",
  "ServiceCode": "buckaroovoucher",
  "IsTest": true,
  "Currency": "EUR",
  "AmountCredit": 10,
  "TransactionType": "V801",
  "MutationType": 2,
  "RelatedTransactions": [
    {
      "RelationType": "refund",
      "RelatedTransactionKey": "3171784167F8478C803090XXXXXXXXXX"
    }
  ],
  "ConsumerMessage": null,
  "Order": null,
  "IssuingCountry": null,
  "StartRecurrent": false,
  "Recurring": false,
  "CustomerName": null,
  "PayerHash": null,
  "PaymentKey": "AF266BBB414F4BB28563BDXXXXXXXXXX"
}

Push


JSON push response

JSON

copy
{
  "Transaction":{
    "Key":"A419347FFC534AE3B34256XXXXXXXXXX",
    "Invoice":"testinvoice 123",
    "ServiceCode":"buckaroovoucher",
    "Status":{
      "Code":{
        "Code":190,
        "Description":"Success"
      },
      "SubCode":null,
      "DateTime":"2020-06-04T09:59:30"
    },
    "IsTest":true,
    "Order":null,
    "Currency":"EUR",
    "AmountCredit":10.00,
    "TransactionType":"V801",
    "Services":null,
    "CustomParameters":null,
    "AdditionalParameters":null,
    "MutationType":2,
    "RelatedTransactions":[
      {
        "RelationType":"refund",
        "RelatedTransactionKey":"3171784167F8478C803090XXXXXXXXXX"
      }
    ],
    "IsCancelable":false,
    "IssuingCountry":null,
    "StartRecurrent":false,
    "Recurring":false,
    "CustomerName":null,
    "PayerHash":null,
    "PaymentKey":null
  }
}

GetBalance

View in playground

Request


JSON gateway request

VoucherCode
Required

VoucherCode of a voucher

JSON

copy
{
  "Currency": "EUR",
  "Services": {
    "ServiceList": [
      {
        "Name": "buckaroovoucher",
        "Action": "GetBalance",
        "Parameters": [
          {
            "Name": "vouchercode",
            "Value": "WP6W-XXXX-XXXX-56T7"
          }
        ]
      }
    ]
  }
}

Response


JSON gateway response

JSON

copy
{
  "Key": "D9BE327DD7A54D99B0B52DXXXXXXXXXX",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2020-06-04T09:35:58"
  },
  "RequiredAction": null,
  "Services": [
    {
      "Name": "buckaroovoucher",
      "Action": null,
      "Parameters": [
        {
          "Name": "CurrentBalance",
          "Value": "17.7500"
        }
      ]
    }
  ],
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "buckaroovoucher",
  "IsTest": true,
  "ConsumerMessage": null
}

CreateApplication

Vouchers can be created through the CreateApplication action, which can either be done through an API request or uploading a batchfile. In case you want to create Vouchers with a batchfile, you can request an example file through support@buckaroo.nl.

View in playground

Request


JSON gateway request

GroupReference

Reference to group vouchers

UsageType
Required

Single (1) or Multiple (2).

ValidFrom
Required

Date from which the voucher is valid.

ValidUntil

Date until which the voucher is valid.

CreationBalance
Required

Value of the voucher.

JSON

copy
{
  "Currency": "EUR",
  "Services": {
    "ServiceList": [
      {
        "Name": "buckaroovoucher",
        "Action": "CreateApplication",
        "Parameters": [
          {
            "Name": "UsageType",
            "Value": "1"
          },
          {
            "Name": "ValidFrom",
            "Value": "2020-06-03"
          },
          {
            "Name": "ValidUntil",
            "Value": "2021-06-03"
          },
          {
            "Name": "CreationBalance",
            "Value": "17.75"
          }
        ]
      }
    ]
  }
}

Response


JSON gateway response

JSON

copy
{
  "Key": "8E64E1B0865C4FB096FCD1XXXXXXXXXX",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2020-06-04T09:29:48"
  },
  "RequiredAction": null,
  "Services": [
    {
      "Name": "buckaroovoucher",
      "Action": null,
      "Parameters": [
        {
          "Name": "VoucherCode",
          "Value": "WP6W-XXXX-XXXX-56T7"
        },
        {
          "Name": "CreationBalance",
          "Value": "17.75"
        },
        {
          "Name": "ValidFrom",
          "Value": "06/03/2020 00:00:00"
        },
        {
          "Name": "ValidUntil",
          "Value": "06/03/2021 00:00:00"
        }
      ]
    }
  ],
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "buckaroovoucher",
  "IsTest": true,
  "ConsumerMessage": null
}

DeactivateVoucher

Perform this call to deactivate an active voucher.

View in playground

Request


Example JSON request

VoucherCode
Required

VoucherCode of an active voucher.

JSON

copy
{
  "Services": {
    "ServiceList": [
      {
        "Name": "buckaroovoucher",
        "Action": "DeactivateVoucher",
        "Parameters": [
          {
            "Name": "VoucherCode",
            "Value": "xxxxxxxxxxxxxxxxxxx"
          },
        ]
      }
    ]
  }
}

Response


Example JSON response

JSON

copy
{
   "Key": "694DDFE90A5646DBA001A015411XXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2020-06-02T13:31:49"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "buckaroovoucher",
   "IsTest": false,
   "ConsumerMessage": null
}