Obligations API

Find out more about the Viva Wallet Obligations API for use with our online marketplace solution. You can use API testing tools such as Postman or Insomnia to make test API calls. The demo environment has a base URL of https://demo-api.vivapayments.com/ and for the live environment it’s https://api.vivapayments.com/.


The Create payment obligation call, below, uses IdentityServer (OAuth 2) authentication but access is given on a case-by-case basis through our development team. You will need to speak to your account manager to arrange this.

API calls

The Viva Wallet Obligations API consists of the following API call.

Create payment obligation

Enables marketplace to pay a seller from the marketplace escrow account.

Request information

post    /obligations/v1/obligations

amountIn decimals rather than the smallest denomination of the currency (0.6 pounds instead of 60 pence).decimalRequired
personIdSeller merchant ID to whom the marketplace will be obligated to send the paymentlongRequired
walletIdUse 'null' unless there is a wallet other than the default primary one that’s being used by the seller for their transactions.longOptional
descriptionA string with extra information you want to show in the transaction once the obligation is cleared.stringOptional
currencyCodeThe 3-digit currency code of the transaction. Should be set to the same currency as the Viva Wallet accounts that form the marketplace.integerRequired
curl -L -X POST 'https://demo-api.vivapayments.com/obligations/v1/obligations' \
-H 'Authorization: Bearer [access token]' \
-H 'Content-Type: application/json' \
--data-raw '{
    "amount": 0.6,
    "personId": "[seller merchant ID]",
    "walletId": null,
    "description": "test",
    "currencyCode": 826

Response information

A valid balance transfer API call will result in HTTP status code 200, "statusId": "A" and generation of a unique obligation ID. Obligations are cleared within an hour. Obligations can be cleared only if the account has enough funds. The obligation is transformed into a transaction once it is cleared. You can use webhooks to perform an action when that happens.

    "captureId": null,
    "statusId": "A",
    "obligationId": "d1539512-95dd-44d6-b5d5-78c8b4f53839",
    "cancellationId": null,
    "created": "2020-11-25T17:26:13.681595+02:00",
    "completed": null,
    "walletTransactionSubTypeId": 159