General

A mobile wallet is the digital equivalent to the physical wallet we already have in our pockets today. It is a container to store digitized valuables. These valuables grant permission for usage or access to goods or services.

The payment flow is as follows: A consumer starts a transaction. The merchant will collect the required wallet information. The required information will be sent to Buckaroo and Buckaroo checks the balance on the Buckaroo Wallet. Buckaroo will check if the total amount that should be paid by the consumer is paid. A push will be sent to the merchant.

The deposit flow: The initiate increase is not part of this manual since the real transaction is not linked to the wallet. When a payment is received the initiate deposit can be used to increase the balance on the Buckaroo Wallet.

The servicecode for a wallet is: buckaroowallet

The following actions are supported:

Transaction requests

  • Pay: Pay the supplied amount via a walletId
  • Refund: Refund the wallet payment Transaction

Data requests

  • Deposit: Deposit the supplied amount to the wallet.
  • GetBalance: Get the current balance and status of a wallet.
  • CreateApplication: Create a new wallet
  • Update: Update the wallet status and customer details.

Pay

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

View in playground

Request


JSON gateway request

WalletId
Required

Wallet identifier in Buckaroo system.

JSON

copy
{
  "Currency": "EUR",
  "AmountDebit": 1.00,
  "Invoice": "testinvoice 123",
  "Services": {
    "ServiceList": [
      {
        "Name": "buckaroowallet",
        "Action": "Pay",
        "Parameters": [
          {
            "Name": "Walletid",
            "Value": "JohnSmithWallet01"
          }
        ]
      }
    ]
  }
}

Response


JSON gateway response

WalletId

Wallet identifier in Buckaroo system.

JSON

copy
{
   "Key": "46FB241693914AA4AE7A8B6DB33DEXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-02-08T10:23:13"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "buckaroowallet",
         "Action": null,
         "Parameters": [
            {
               "Name": "WalletId",
               "Value": "JohnSmithWallet01"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "buckaroowallet",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 1,
   "TransactionType": "V802",
   "MutationType": 2,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "John Smith",
   "PayerHash": null,
   "PaymentKey": "DF7CC74BFBD54DF3B5CCCFF1171B3XXX"
}

Push


JSON push response

WalletId

Wallet identifier in Buckaroo system.

JSON

copy
{
   "Transaction": {
      "Key": "46FB241693914AA4AE7A8B6DB33DEXXX",
      "Invoice": "testinvoice 123",
      "ServiceCode": "buckaroowallet",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
         },
         "DateTime": "2018-02-08T10:23:13"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountDebit": 1,
      "TransactionType": "V802",
      "Services": [
         {
            "Name": "buckaroowallet",
            "Action": null,
            "Parameters": [
               {
                  "Name": "WalletId",
                  "Value": "JohnSmithWallet01"
               }
            ],
            "VersionAsProperty": 1
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 2,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": "John Smith",
      "PayerHash": null,
      "PaymentKey": "DF7CC74BFBD54DF3B5CCCFF1171B3XXX"
   }
}

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

JSON

copy
{
   "Currency": "EUR",
   "AmountCredit": 1.00,
   "Invoice": "testinvoice 123",
   "OriginalTransactionKey": "46FB241693914AA4AE7A8B6DB33DEXXX",
   "Services": {
      "ServiceList": [
         {
            "Name": "buckaroowallet",
            "Action": "Refund"
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "49B018248ECE4346AC20B9020DADEXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-02-08T10:26:15"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "buckaroowallet",
   "IsTest": true,
   "Currency": "EUR",
   "AmountCredit": 1,
   "TransactionType": "V803",
   "MutationType": 2,
   "RelatedTransactions": [
      {
         "RelationType": "refund",
         "RelatedTransactionKey": "46FB241693914AA4AE7A8B6DB33DEXXX"
      }
   ],
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": null,
   "PayerHash": null,
   "PaymentKey": "3E6437D538BB469FBA723A30BC33AXXX"
}

Push


JSON push response

JSON

copy
{
   "Transaction": {
      "Key": "49B018248ECE4346AC20B9020DADEXXX",
      "Invoice": "testinvoice 123",
      "ServiceCode": "buckaroowallet",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": null,
         "DateTime": "2018-02-08T10:26:15"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountCredit": 1,
      "TransactionType": "V803",
      "Services": null,
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 2,
      "RelatedTransactions": [
         {
            "RelationType": "refund",
            "RelatedTransactionKey": "46FB241693914AA4AE7A8B6DB33DEXXX"
         }
      ],
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": null,
      "PayerHash": null,
      "PaymentKey": null
   }
}

GetBalance

The GetBalance request is used to get information about the current balance and the current status of the wallet. Please note that this is a data request, not a transaction request.

View in playground

Request


JSON gateway request

WalletId
Required

Wallet identifier in Buckaroo system.

JSON

copy
{
   "Services": {
      "ServiceList": [
         {
            "Name": "buckaroowallet",
            "Action": "GetBalance",
            "Parameters": [
               {
                  "Name": "Walletid",
                  "Value": "JohnSmithWallet01"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

WalletId

Wallet identifier in Buckaroo system.

CurrentStatus

Wallet current status. 1 = active 2 = disabled

LastUpdated

Last balance mutation on the wallet.

CurrentBalance

Wallet current balance amount.

WalletCurrency

Wallet currency

JSON

copy
{
   "Key": "FBBA59013EB7458D8964FF4A31265XXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-02-08T10:32:28"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "buckaroowallet",
         "Action": null,
         "Parameters": [
            {
               "Name": "CurrentBalance",
               "Value": "99.0000"
            },
            {
               "Name": "LastUpdated",
               "Value": "02/08/2018 10:26:15"
            },
            {
               "Name": "WalletId",
               "Value": "JohnSmithWallet01"
            },
            {
               "Name": "CurrentStatus",
               "Value": "1"
            },
            {
               "Name": "WalletCurrency",
               "Value": "EUR"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "buckaroowallet",
   "IsTest": true,
   "ConsumerMessage": null
}

CreateApplication

The CreateApplication request is used to make a new wallet. It is possible to give customer details but this is not required. Customer details can be added or changed on a later moment through the Update request. The WalletId must be unique, regardless of test or live, for the uses merchant account. It is not possible to delete a wallet.

View in playground

Request


JSON gateway request

Currency
Required

Three-letter currency code (only EUR is supported) Note: this is a basic field.

WalletId
Required

Wallet identifier in Buckaroo system.

CurrentStatus
Required

Wallet status on creation. Possible values 1: active, 2: disabled

CreationBalance
Required

Balance amount on creation. Amount must be 0 or greater than 0.

CustomerLastName

Lastname for the customer.

CustomerFirstName

Fistname for the customer.

CustomerInitials

Initials for the customer.

CustomerEmail

E-mail address for the customer.

JSON

copy
{
   "Currency": "EUR",
   "Services": {
      "ServiceList": [
         {
            "Name": "buckaroowallet",
            "Action": "CreateApplication",
            "Parameters": [
               {
                  "Name": "CurrentStatus",
                  "Value": "1"
               },
               {
                  "Name": "CreationBalance",
                  "Value": "100.00"
               },
               {
                  "Name": "CustomerLastName",
                  "Value": "Smith"
               },
               {
                  "Name": "CustomerFirstName",
                  "Value": "John"
               },
               {
                  "Name": "CustomerEmail",
                  "Value": "your@email.nl"
               },
               {
                  "Name": "Walletid",
                  "Value": "JohnSmithWallet01"
               },
               {
                  "Name": "CustomerInitials",
                  "Value": "JS"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

WalletId

Wallet identifier in Buckaroo system.

CurrentBalance

Balance for wallet after creation.

JSON

copy
{
   "Key": "F43FE554C65C4B179E9410E6E52B5XXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-02-08T10:14:31"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "buckaroowallet",
         "Action": null,
         "Parameters": [
            {
               "Name": "WalletId",
               "Value": "JohnSmithWallet01"
            },
            {
               "Name": "CurrentBalance",
               "Value": "100.00"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "buckaroowallet",
   "IsTest": true,
   "ConsumerMessage": null
}

Deposit

The Deposit request is used to make a deposit for a wallet.

View in playground

Request


JSON gateway request

Amount
Required

Amount to be added to the wallet. Note: this is a basic field.

Currency
Required

Three-letter currency code (only EUR is supported) Note: this is a basic field.

WalletId
Required

Wallet identifier in Buckaroo system.

JSON

copy
{
   "Currency": "EUR",
   "Amount": 1,
   "Services": {
      "ServiceList": [
         {
            "Name": "buckaroowallet",
            "Action": "Deposit",
            "Parameters": [
               {
                  "Name": "Walletid",
                  "Value": "JohnSmithWallet01"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

WalletId

Wallet identifier in Buckaroo system.

CurrentBalance

Wallet current balance amount.

JSON

copy
{
   "Key": "BCF5CD8507AB4C1891CFE15F3F4DBXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-02-08T11:12:12"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "buckaroowallet",
         "Action": null,
         "Parameters": [
            {
               "Name": "CurrentBalance",
               "Value": "101.0000"
            },
            {
               "Name": "WalletId",
               "Value": "JohnSmithWallet01"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "buckaroowallet",
   "IsTest": true,
   "ConsumerMessage": null
}

Update

The Update request is manly used to update the wallet status but it can also be used to change customer details. The CurrentStatus is always part of this request even when you only want to change customer details so take care to send in the correct status.

When no customer details fields are send in the request we leave the current customer details on the wallet, when you send in fields with an empty values for the customer details we update the customer details to an empty value.

View in playground

Request


JSON gateway request

WalletId
Required

Wallet identifier in Buckaroo system.

CurrentStatus
Required

Possible values 1: active, 2: disabled

CustomerLastName

Last name for the customer.

CustomerFirstName

First name for the customer.

CustomerInitials

Initials for the customer.

CustomerEmail

E-mail address for the customer.

JSON

copy
{
   "Services": {
      "ServiceList": [
         {
            "Name": "buckaroowallet",
            "Action": "Update",
            "Parameters": [
               {
                  "Name": "CustomerFirstName",
                  "Value": "John"
               },
               {
                  "Name": "CustomerEmail",
                  "Value": "your@email.nl"
               },
               {
                  "Name": "CustomerInitials",
                  "Value": "JS"
               },
               {
                  "Name": "CurrentStatus",
                  "Value": "1"
               },
               {
                  "Name": "Walletid",
                  "Value": "JohnSmithWallet01"
               },
               {
                  "Name": "CustomerLastName",
                  "Value": "Smith"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "2F4B4ACB3D004CB29ADBE406A6396XXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-02-08T11:16:33"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "buckaroowallet",
   "IsTest": true,
   "ConsumerMessage": null
}