Home › Connect › Volt Accounts

Accounts by Volt

Only for Volt Accounts hosted by Volt

The functionality listed here only applies to Volt Accounts. Note that this does not include Volt Connect via any of our partners.

Volt offers transactional accounts to selected customers – we call them Volt Accounts (this is separate from our Connect functionality) . A Volt Account is an account used by Volt’s merchants to receive funds (including shopper payments initiated by Volt) and paying out to other parties like suppliers.  It provides Volt merchants an efficient and secure way to manage financial transactions.

Note: Volt Accounts are currently in beta, and we are actively working to enhance their functionality. Talk to your Sales representative or Delivery Manager for more details.

Initial setup at Volt

  1. You’ll need to provide a webhook URL to which all notifications will be sent by Volt.
  2. To start integrating you need to have the following details (thse will be provided to you by the Volt Implementation Team):
    • username
    • password
    • notification secret
  3. After your onboarding for Volt Accounts, you will receive the account details, e.g.: IBAN and Volt account identifier

Authentication

Every request must contain an authorisation header:

Authorization: Bearer {token}

How to generate the JWT token:

  • Token is constructed from JWT header, empty payload, and JWS signature.
  • JWT header must contain “kid” field with your API key identifier
  • JWS signature is constructed from JWT header, original request payload and your API secret

JWT_Header:
{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "YOUR_API_KEY_GOES_HERE"
}

JWT Payload (detached, empty): 
""

JWT Signature:
HMACSHA256(
  base64UrlEncode(JWT_Header) + "." +
  base64UrlEncode(request_payload),
  YOUR_API_SECRET_GOES_HERE
)


request_payload:
{"requestPayload": "some_payload"}

Example token, where:

  • kid = YOUR_API_KEY_GOES_HERE
  • secret = YOUR_API_SECRET_GOES_HERE
  • payload = {“requestPayload”: “some_payload”}

Result, signature is red:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IllPVVJfQVBJX0tFWV9HT0VTX0hFUkUifQ...

tIkEiumeKx7iLHX_Rk78jVvByV5KhnedjqCCJGVEXcM

Pay-Ins (Incoming funds)

Volt sends a notification to your webhook URL every time funds are credited to your Connect Account.

Webhook

Every time the new pay-in transfer will come into your account, a notification will be triggered at Volt and sent to the webhook URL provided during onboarding.

Notification Delivery

Volt will attempt to send notifications to the provided URL.  Once received you should return an HTTP 200 response code.

If a the response is not received, or it is not 200, we will retry 10 times with an incremental delay.  After the first failure, our support team will be notified and will be in contact with you.

After the 10th failure, Volt will no longer retry.

Notification security

A checksum is provided in the notification headers. It is calculated using your notification secret, and the notification body. This way you can be sure that the notification has been sent by Volt, and has not been modified.

Notification Headers

  • Content-Type
  • checksum

Notification Body

Notification body 
{
  "eventId": "49adf8f3-74b7-4bf3-a44c-94a40e5243dc",
  "notificationType": "credit_received",
  "timestamp": "2023-10-16T16:39:47+00:00",
  "transactionDetails": {
    "id": "cdedad56-7040-47a1-9eed-a4bae9555f5b",
    "status": "SUCCESS",
    "errors": [],
    "debtorDetails": {
      "debtorAccount": {
        "accountNumber": "NL08INGB4824538831",
        "financialInstitution": "123123",
        "country": "NL"
      },
      "debtorName": "Funding of test account",
      "debtorAddress": null,
      "viban": null
    },
    "debitAmount": {
      "amount": "1000",
      "currency": "EUR"
    },
    "date": "2023-10-16T16:39:40+00:00",
    "remittanceInfo": {
      "line1": "demo 12",
      "line2": null,
      "line3": null,
      "line4": null
    },
    "externalId": "37d3e7a4-df21-406e-907d-d52310732000",
    "creditorDetails": {
      "creditorAccount": {
        "accountNumber": null,
        "financialInstitution": null,
        "country": null
      },
      "creditorName": null,
      "creditorAddress": null,
      "viban": "DK2450517187342686"
    },
    "creditAmount": {
      "amount": "1000",
      "currency": "EUR"
    },
    "payerTransactionReference": null
  }
}

Notification Body Fields

eventType uuid notification identifier

notificationType

 string credit_received
timestamp timestamp timestamp when notification was created and sent
transactionDetails.id uuid Volt transaction identifier
transactionDetails.status string always SUCCESS for incoming funds
transactionDetails.errors array empty for incoming funds
transactionDetails.debtorDetails.debtorAccount.accountNumber string IBAN or Account Number
transactionDetails.debtorDetails.debtorAccount.financialInstitution string SWIFT/BIC or Sort code
transactionDetails.debtorDetails.debtorAccount.country string country code
transactionDetails.debtorDetails.debtorName string payer name
transactionDetails.debtorDetails.debtorAddress JSON {
“line1”: “LIPOLOL 25”,
“line2”: “AMSTERDAM”,
“line3”: null
}
transactionDetails.debtorDetails.viban string payer virtual IBAN number (if available)
transactionDetails.debitAmount.amount integer amount in minor units
transactionDetails.debitAmount.currency string currency code
transactionDetails.date timestamp  
transactionDetails.remittanceInfo JSON {
“line1”: “Description that Shopper provides 35 max”,
“line2″: ” in each line Ref$444231 can be more”,
“line3”: null,
“line4”: null
}
transactionDetails.externalId uuid transaction identifier at banking provider (if available)
transactionDetails.creditorDetails.creditorAccount.accountNumber string IBAN or Account Number
transactionDetails.creditorDetails.creditorAccount.financialInstitution string SWIFT/BIC or Sort code
transactionDetails.creditorDetails.creditorAccount.country string country code
transactionDetails.creditorDetails.creditorName string beneficiary name
transactionDetails.creditorDetails.creditorAddress JSON {
“line1”: “LIPOLOL 25”,
“line2”: “AMSTERDAM”,
“line3”: null
}
transactionDetails.creditorDetails.viban string virtual IBAN number
transactionDetails.creditAmount.amount integer amount in minor units
transactionDetails.creditAmount.currency string currency code

 

How to Test

On the sandbox environment, we can simulate incoming credits by using the endpoint:

POST /notification/mock-provider-1

Our system acts as if funds were received to your account.

Volt can provide endpoint documentation on request if you wish to perform your own testing.

Pay-Outs (Outgoing funds)

You can use our generic /api/payouts endpoint in order to send any type of payment:

  • Refund/Payout
  • Settlement – has less restrictive anti-fraud monitoring rules

In order to use Settlements properly, provide an account IBAN to Volt. If the payment is sent to your own account, Volt can recognise this and apply less restrictive monitoring rules.

How to Test

You can simulate payment flows on Sandbox using specific payout amounts:

On Sandbox environment we can use Mock Banking Provider to simulate various payout behaviours based on payout amount:

  • if amount is 20 you will receive payout_rejected and payout will be FAIL
  • if amount is 40 you will receive payout_rejected and payout will be FAIL
  • if amount is 60 you will not receive any notification and payout will be stuck in PENDING

If there is sufficient balance on the account, any other payment amount should result in SUCCESS.

Headers: authorization

Request

POST /api/payouts 
{
    "amount": 1, //amount in minor units
    "currency": "EUR", //currency of the transfer
    "accountId": "{{accountId}}", //"volt account id" of the sender account, not to be confused by "Unique ID for API"
    "reference": "pay demo", //remittance information
    "creditorAccount": { //account details of the beneficiary account
        "iban": "DK6689000099105309",
        "swiftBic": "SXPYDKKKXXX"
    },
    "creditorName": "John Bloggs", //beneficiary name
    "creditorAddress": "1 Street, ABC123 Berlin, DE", //beneficiary address
    "payerTransactionReference": "payerReference" //custom reference, unique!
}
Response - 201 
{
    "message": "Payout request has been created successfully.",
    "id": "f8b4f0d3-5eba-462b-84eb-0a5203a8be3c" //Volt transaction ID
}

Any other HTTP code (40x , 50x) indicates that the payment request was not created (details will be provided in the ”message” field)

GET /api/payouts 
[
    {
        "id": "d0aa3176-ea0f-44ab-a0eb-dcabc01f2bf2",
        "reference": "payment demo 2",
        "externalReference": null,
        "amount": "13",
        "currency": "EUR",
        "status": "completed",
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "creditorAccount": {
            "bic": "RABONL2UXXX",
            "iban": "NL11RABO4097012428",
            "accountName": "John Bloggs",
            "accountAddress": "1 Street, ABC123 Berlin, DE"
        },
        "creditorName": "John Bloggs",
        "creditorAddress": "1 Street, ABC123 Berlin, DE",
        "valueData": "2023-10-16 16:51:01",
        "instructedTimestamp": null
    },
    {
        "id": "bf0efb70-a8fd-432f-85f4-683191d70a94",
        "reference": "payment demo 1",
        "externalReference": null,
        "amount": "1",
        "currency": "EUR",
        "status": "completed",
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "creditorAccount": {
            "bic": "RABONL2UXXX",
            "iban": "NL11RABO4097012428",
            "accountName": "John Bloggs",
            "accountAddress": "1 Street, ABC123 Berlin, DE"
        },
        "creditorName": "John Bloggs",
        "creditorAddress": "1 Street, ABC123 Berlin, DE",
        "valueData": "2023-10-16 16:50:36",
        "instructedTimestamp": null
    },
    {
        "id": "b7d8f12a-82b5-4aae-99e2-0525b1ce3528",
        "reference": "payment demo 2",
        "externalReference": null,
        "amount": "20",
        "currency": "EUR",
        "status": "failed",
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "creditorAccount": {
            "bic": "RABONL2UXXX",
            "iban": "NL11RABO4097012428",
            "accountName": "John Bloggs",
            "accountAddress": "1 Street, ABC123 Berlin, DE"
        },
        "creditorName": "John Bloggs",
        "creditorAddress": "1 Street, ABC123 Berlin, DE",
        "valueData": null,
        "instructedTimestamp": null
    },
    {
        "id": "5148aff1-c0b8-4cc1-ba6f-e6c55db17c03",
        "reference": "payment demo 2",
        "externalReference": null,
        "amount": "60",
        "currency": "EUR",
        "status": "pending",
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "creditorAccount": {
            "bic": "RABONL2UXXX",
            "iban": "NL11RABO4097012428",
            "accountName": "John Bloggs",
            "accountAddress": "1 Street, ABC123 Berlin, DE"
        },
        "creditorName": "John Bloggs",
        "creditorAddress": "1 Street, ABC123 Berlin, DE",
        "valueData": null,
        "instructedTimestamp": "2023-10-16 16:52:41"
    },
    {
        "id": "a1b6df1c-0bc0-4b4c-aad3-6d7ddb266802",
        "reference": "payment demo 2",
        "externalReference": null,
        "amount": "13",
        "currency": "EUR",
        "status": "completed",
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "creditorAccount": {
            "bic": "RABONL2UXXX",
            "iban": "NL11RABO4097012428",
            "accountName": "John Bloggs",
            "accountAddress": "1 Street, ABC123 Berlin, DE"
        },
        "creditorName": "John Bloggs",
        "creditorAddress": "1 Street, ABC123 Berlin, DE",
        "valueData": "2023-10-16 16:51:06",
        "instructedTimestamp": null
    },
    {
        "id": "12b7a711-b1b3-435e-b38a-6f3728032784",
        "reference": "payment demo 2",
        "externalReference": null,
        "amount": "20",
        "currency": "EUR",
        "status": "failed",
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "creditorAccount": {
            "bic": "RABONL2UXXX",
            "iban": "NL11RABO4097012428",
            "accountName": "John Bloggs",
            "accountAddress": "1 Street, ABC123 Berlin, DE"
        },
        "creditorName": "John Bloggs",
        "creditorAddress": "1 Street, ABC123 Berlin, DE",
        "valueData": null,
        "instructedTimestamp": null
    },
    {
        "id": "b0d8cb03-2276-45b9-b402-841dd3a4d68d",
        "reference": "payment demo 2",
        "externalReference": null,
        "amount": "40",
        "currency": "EUR",
        "status": "rejected",
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "creditorAccount": {
            "bic": "RABONL2UXXX",
            "iban": "NL11RABO4097012428",
            "accountName": "John Bloggs",
            "accountAddress": "1 Street, ABC123 Berlin, DE"
        },
        "creditorName": "John Bloggs",
        "creditorAddress": "1 Street, ABC123 Berlin, DE",
        "valueData": null,
        "instructedTimestamp": null
    }
]
GET /api/payouts/{payoutId} 
{
    "id": "d0aa3176-ea0f-44ab-a0eb-dcabc01f2bf2",
    "reference": "payment demo 2",
    "externalReference": null,
    "amount": "13",
    "currency": "EUR",
    "status": "completed",
    "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
    "creditorAccount": {
        "bic": "RABONL2UXXX",
        "iban": "NL11RABO4097012428",
        "accountName": "John Bloggs",
        "accountAddress": "1 Street, ABC123 Berlin, DE"
    },
    "creditorName": "John Bloggs",
    "creditorAddress": "1 Street, ABC123 Berlin, DE",
    "valueData": "2023-10-16 16:51:01",
    "instructedTimestamp": null
}

Webhook

Once created, payment request is being processed by Volt and Volt banking partner. Notification is sent when the processing is complete.

Notification body 
{
  "notificationType": "payout_completed",
  "timestamp": "2023-02-21T22:10:43+0000",
  "transactionDetails": {
    "id": "c3000ea5-05a9-4d1a-816f-26b570f6d70e",
    "status": "SUCCESS",
    "errors": [],
    "debtorDetails": {
      "debtorAccount": {
        "accountNumber": null,
        "financialInstitution": null,
        "country": null
      },
      "debtorName": null,
      "debtorAddress": null,
      "viban": "NL31HKOT5224030013"
    },
    "debitAmount": {
      "amount": "10",
      "currency": "EUR"
    },
    "date": "2023-02-21T22:10:40+00:00",
    "remittanceInfo": {
      "line1": "pay demo",
      "line2": null,
      "line3": null,
      "line4": null
    },
    "externalId": null,
    "creditorDetails": {
      "creditorAccount": {
        "accountNumber": "DK6689000099105309",
        "financialInstitution": null,
        "country": null
      },
      "creditorName": "John Bloggs",
      "creditorAddress": "1 Street, ABC123 Berlin, DE",
      "viban": null
    },
    "creditAmount": {
      "amount": "10",
      "currency": "EUR"
    }
  }
}

Payout Confirmation

Sent when the payment has been confirmed by the banking partner.

"notificationType": "payout_completed",
"transactionDetails"."status": "SUCCESS",

Payout Failure or Rejection

Sent when the payment fails to process at Volt.

"notificationType": "payout_rejected",
"transactionDetails"."status": "FAIL",

Account Management

Volt provides an API to get basic details regarding every Connect Account.

List all accounts

GET /api/accounts 
{
    "accountId": "0db9c3f7-4dee-426e-bd84-86a862c30d88",
    "account": {
        "iban": "DK5250514614196798"
    },[
    {
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "account": {
            "iban": "DK2450517187342686"
        },
        "balance": "1973",
        "availableBalance": "1913",
        "currencyCode": "EUR",
        "timestamp": "2023-10-16T16:52:37+00:00"
    },
    {
        "accountId": "0db9c3f7-4dee-426e-bd84-86a862c30d88",
        "account": {
            "iban": "DK5250514614196798"
        },
        "balance": "3000",
        "availableBalance": "3000",
        "currencyCode": "EUR",
        "timestamp": "2023-10-16T16:45:02+00:00"
    }
]
    "balance": "0",
    "availableBalance": "0",
    "currencyCode": "EUR",
    "timestamp": "2023-10-16T16:21:48+00:00"
}

Balance/detail of a specific account

GET /api/accounts/{accountId} 
[
    {
        "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
        "account": {
            "iban": "DK2450517187342686"
        },
        "balance": "1973",
        "availableBalance": "1913",
        "currencyCode": "EUR",
        "timestamp": "2023-10-16T16:52:37+00:00"
    },
    {
        "accountId": "0db9c3f7-4dee-426e-bd84-86a862c30d88",
        "account": {
            "iban": "DK5250514614196798"
        },
        "balance": "3000",
        "availableBalance": "3000",
        "currencyCode": "EUR",
        "timestamp": "2023-10-16T16:45:02+00:00"
    }
]

Transaction history

Parameters:

 NAME  TYPE  DESCRIPTION
 dateFrom  YYYY-MM-DD    date in UTC
 dateTo  YYYY-MM-DD  date in UTC
 payerTransactionId   string  transaction id set by payer 
 type  string  debit / credit
 debtorIban  string  
 creditorIban  string  

 

Note: Only shows successful debits and credits. Does not show failed ones

 

GET /api/accounts/{accountId}/transactions 
{
    "accountId": "5aab1a5d-1647-45a3-956e-ce73ac813908",
    "dateFrom": "2023-09-01",
    "dateTo": "2023-10-26",
    "transactions": [
        {
            "id": "70e3783a-7129-43de-9f50-541bf2566a0b",
            "createdAt": "2023-10-16T17:20:35+00:00",
            "type": "internal",
            "reference": "2st transfer",
            "status": "completed",
            "amount": "100",
            "currency": "EUR",
            "debtorInformation": null,
            "creditorInformation": null
        },
        {
            "id": "5523755e-28b3-4e72-88c3-3dae870b16a8",
            "createdAt": "2023-10-16T17:18:19+00:00",
            "type": "internal",
            "reference": "1st transfer",
            "status": "completed",
            "amount": "100",
            "currency": "EUR",
            "debtorInformation": null,
            "creditorInformation": null
        },
        {
            "id": "f9126890-1180-4cd3-b477-9995ee09dd04",
            "createdAt": "2023-10-16T16:51:01+00:00",
            "type": "debit",
            "reference": "payment demo 2",
            "status": "completed",
            "amount": "13",
            "currency": "EUR",
            "debtorInformation": null,
            "creditorInformation": {
                "bic": "RABONL2UXXX",
                "iban": "NL11RABO4097012428",
                "accountName": "John Bloggs",
                "accountAddress": "1 Street, ABC123 Berlin, DE"
            }
        },
        {
            "id": "42704b00-593b-4bd2-b6b3-29f59c1ca1c6",
            "createdAt": "2023-10-16T16:50:54+00:00",
            "type": "debit",
            "reference": "payment demo 2",
            "status": "completed",
            "amount": "13",
            "currency": "EUR",
            "debtorInformation": null,
            "creditorInformation": {
                "bic": "RABONL2UXXX",
                "iban": "NL11RABO4097012428",
                "accountName": "John Bloggs",
                "accountAddress": "1 Street, ABC123 Berlin, DE"
            }
        },
        {
            "id": "a6d4551d-98ff-4d02-81b5-8431f59a10d7",
            "createdAt": "2023-10-16T16:50:30+00:00",
            "type": "debit",
            "reference": "payment demo 1",
            "status": "completed",
            "amount": "1",
            "currency": "EUR",
            "debtorInformation": null,
            "creditorInformation": {
                "bic": "RABONL2UXXX",
                "iban": "NL11RABO4097012428",
                "accountName": "John Bloggs",
                "accountAddress": "1 Street, ABC123 Berlin, DE"
            }
        },
        {
            "id": "2f7e290b-bb60-42bd-b5f4-2d150194df44",
            "createdAt": "2023-10-16T16:39:52+00:00",
            "type": "credit",
            "reference": "demo 14",
            "status": "completed",
            "amount": "1000",
            "currency": "EUR",
            "debtorInformation": {
                "iban": "NL08INGB4824538831",
                "country": "NL",
                "routing": "123123",
                "accountName": "Funding of test account",
                "accountAddress": "25 Debtor Testing Str."
            },
            "creditorInformation": null
        },
        {
            "id": "6d7a404a-7ee8-4850-a8f0-f7436cc41245",
            "createdAt": "2023-10-16T16:39:47+00:00",
            "type": "credit",
            "reference": "demo 12",
            "status": "completed",
            "amount": "1000",
            "currency": "EUR",
            "debtorInformation": {
                "iban": "NL08INGB4824538831",
                "country": "NL",
                "routing": "123123",
                "accountName": "Funding of test account",
                "accountAddress": "25 Debtor Testing Str."
            },
            "creditorInformation": null
        }
    ]
}

Please note that all data formats and structures detailed on this page are subject to change before final confirmation.

← Previous Payment Processing Times
Next → Payments received