Obligations API

The Obligations API is used with our marketplace solution.

This API call is available if you are a Viva Wallet marketplace owner. Please speak to your Viva Wallet sales representative to request access. Alternatively, you can contact us directly via our live chat facility. Simply click on the live chat icon in the bottom right-hand corner of this page.


The Create payment obligation call, below, uses IdentityServer (OAuth 2) authentication.


The demo environment has a base URL of https://demo-api.vivapayments.com/ and for the live environment it’s https://api.vivapayments.com/.

API calls

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

Create payment obligation

Enables marketplace owner to place an obligation to a seller for payback in case of a customer refund. When the obligation is captured, Viva Wallet will transfer money from the seller account to the platform account. The identity of the transfer recipient (platform account) is implied in the credentials used for the API call’s authentication. The identity of the sender (seller) is acquired from the personID (Viva Wallet Merchant ID) defined as a body parameter in the API call.

Request information

post    /obligations/v1/obligations

amountIn decimals rather than the smallest denomination of the currency (£0.6 instead of 60p).decimalRequired
personIdSeller merchant ID from which the refund payback is being requested.longRequired
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 captured.stringOptional
currencyCodeThe 3-digit currency code of the transaction. Should be set to the same currency as the Viva Wallet accounts involved in the obligation call.integerRequired
curl -L -X POST 'https://demo-api.vivapayments.com/obligations/v1/obligations' \
-H 'Authorization: Bearer [platform account access token]' \
-H 'Content-Type: application/json' \
--data-raw '{
    "amount": "0.6",
    "personId": "[seller merchant ID]",
    "walletId": "[seller wallet ID]",
    "description": "test",
    "currencyCode": 826

Run in Postman

Response information

A valid obligation API call will result in HTTP status code 200, "statusId": "A" and generation of a unique obligation ID. Obligations are captured within an hour. Obligations can be captured only if the account has enough funds (the entire amount), otherwise the obligation remains in a status of pending. A check is performed several times a day until the account has sufficient funds. The obligation is transformed into a transaction once it is captured. You can use a webhook to be notified of the capture and perform a subsequent action.

The obligation will not be visible on the marketplace seller dashboard until it is captured and becomes a transaction. However, the total balance will include the value of the obligation.

    "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

Further information

Check out the related tutorials below for more details on the topics already covered: