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.
Request
JSON gateway request
|
WalletId
string
|
Required
Wallet identifier in Buckaroo system. |
JSON
{
"Currency": "EUR",
"AmountDebit": 1.00,
"Invoice": "testinvoice 123",
"Services": {
"ServiceList": [
{
"Name": "buckaroowallet",
"Action": "Pay",
"Parameters": [
{
"Name": "Walletid",
"Value": "JohnSmithWallet01"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
WalletId
string
|
Wallet identifier in Buckaroo system. |
JSON
{
"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
string
|
Wallet identifier in Buckaroo system. |
JSON
{
"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.
Request
JSON gateway request
JSON
{
"Currency": "EUR",
"AmountCredit": 1.00,
"Invoice": "testinvoice 123",
"OriginalTransactionKey": "46FB241693914AA4AE7A8B6DB33DEXXX",
"Services": {
"ServiceList": [
{
"Name": "buckaroowallet",
"Action": "Refund"
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
JSON
{
"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
{
"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.
Request
JSON gateway request
|
WalletId
string
|
Required
Wallet identifier in Buckaroo system. |
JSON
{
"Services": {
"ServiceList": [
{
"Name": "buckaroowallet",
"Action": "GetBalance",
"Parameters": [
{
"Name": "Walletid",
"Value": "JohnSmithWallet01"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
WalletId
string
|
Wallet identifier in Buckaroo system. |
|
CurrentStatus
integer
|
Wallet current status. 1 = active 2 = disabled |
|
LastUpdated
date
|
Last balance mutation on the wallet. |
|
CurrentBalance
decimal
|
Wallet current balance amount. |
|
WalletCurrency
string
|
Wallet currency |
JSON
{
"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.
Request
JSON gateway request
|
Currency
string
|
Required
Three-letter currency code (only EUR is supported) Note: this is a basic field. |
|
WalletId
string
|
Required
Wallet identifier in Buckaroo system. |
|
CurrentStatus
integer
|
Required
Wallet status on creation. Possible values 1: active, 2: disabled |
|
CreationBalance
decimal
|
Required
Balance amount on creation. Amount must be 0 or greater than 0. |
|
CustomerLastName
string
|
Lastname for the customer. |
|
CustomerFirstName
string
|
Fistname for the customer. |
|
CustomerInitials
string
|
Initials for the customer. |
|
CustomerEmail
string
|
E-mail address for the customer. |
JSON
{
"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 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
WalletId
string
|
Wallet identifier in Buckaroo system. |
|
CurrentBalance
|
Balance for wallet after creation. |
JSON
{
"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
}Request
JSON
{
"Currency": "EUR",
"Amount": 1,
"Services": {
"ServiceList": [
{
"Name": "buckaroowallet",
"Action": "Deposit",
"Parameters": [
{
"Name": "Walletid",
"Value": "JohnSmithWallet01"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
WalletId
string
|
Wallet identifier in Buckaroo system. |
|
CurrentBalance
decimal
|
Wallet current balance amount. |
JSON
{
"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 mainly 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.
Request
JSON gateway request
|
WalletId
string
|
Required
Wallet identifier in Buckaroo system. |
|
CurrentStatus
integer
|
Required
Possible values 1: active, 2: disabled |
|
CustomerLastName
string
|
Last name for the customer. |
|
CustomerFirstName
string
|
First name for the customer. |
|
CustomerInitials
string
|
Initials for the customer. |
|
CustomerEmail
string
|
E-mail address for the customer. |
JSON
{
"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 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
JSON
{
"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
}