VevoPay API

This is an examplary documentation for the VevoPay API. You can take a look at our swagger at: https://[subdomain].vevopay.io/swagger/index.html

Prerequisites

Firstly you will need some credentials. Namely:

  • WebApiKey: We will provide this to you personally.
  • SecretKey: Also provided personally.

You can ask for these values through shared communication channels. We also ask for a callback URL to be assigned and needed IP addresses to be whitelisted.

Please remind our staff if we do not ask for these values!

Table of Contents

  1. Introduction
  2. Depositing with iFrames
  3. Withdrawals
  4. Receiving Callbacks
  5. Calculating Hash Codes
  6. Native API

Depositing with iFrames

Here is the curl for an examplary iFrame deposit request.

curl -X 'POST' \
  'https://grassman.vevopay.io/Transaction/CreateDeposit' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'X-XSRF-TOKEN: null' \
  -d '{
  "amount": 50,
  "userId": "string",
  "name": "string",
  "username": "string",
  "referenceId": "hello-vevopay",
  "transactionType": 1,
  "paymentMethod": 1,
  "hashCode": "F5D83BE4E9F03619FC8D5E96C334D2FF"
}'

The parameters are:

  • amount: Amount to be deposited.
  • userId: Unique ID for the depositing customer.
  • name: Name & Surname of the depositing customer.
  • username: Username of the depositing customer.
  • referenceId: The unique ID for this transaction. We recommend using UUIDv4 standard.
  • transactionType: Static value 1. Signifies this transaction being a deposit.
  • paymentMethod: For a complete list, see our swagger docs.
  • hashCode: See Calculating Hash Codes

If successful, the response body will contain a url field. Customer must be redirect to this url to fulfill the deposit.

See Receiving Callbacks to learn how to verify deposits (or reject) after this step.

Withdrawals

To create a withdraw, here is an examplary curl one-liner:

curl -X 'POST' \
  'https://grassman.vevopay.io/api/services/app/TransactionRequests/CreateWithdraw' \
  -H 'accept: text/plain' \
  -H 'WebApiKey: 5FA6CE55-B9FF-40D0-BFD5-1642D53B3C37' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'X-XSRF-TOKEN: null' \
  -d '{
  "accountNumber": "string",
  "amount": 1,
  "userId": "string",
  "name": "string",
  "username": "string",
  "referenceId": "hello-vevopay-withdraw",
  "transactionType": 2,
  "paymentMethod": 1,
  "hashCode": "5B2CE161F978B6EB95042596D1DBB5E6"
}'

Parameters are:

  • identityNumber: (optional) identity number of the withdrawing customer.
  • accountNumber: The receiver ID (Papara account number, IBAN etc ) of the withdrawing customer.
  • userId: Unique ID of the withdrawing user.
  • name: Name & Surname of the withdrawing user.
  • username: Username of the withdrawing user.
  • referenceId: Unique ID for this withdraw.
  • transactionType: Static value of 2.
  • paymentMethod: For a complete list, see our swagger docs.
  • hashCode: See Calculating Hash Codes

If successful, you will see a withdraw request appear on our dashboard's withdrawals page. At this point it is up to you to either pay & complete or cancel the withdrawals without paying.

Receiving Callbacks

Upon any change to a transfer's (deposit/withdrawal) status, we will programmatically notify a predefined HTTP (POST) endpoint.

Here's an examplary payload we will send:

{
    "Status": 2, // Pending = 1, Completed = 2, ManualControl = 3, Cancelled = 4, Failed = 5
    "StatusDescription": "Completed",
    "TrackingId": "f3a8948b-a6aa-48e3-b1a8-14b7df318e9c",
    "RefereneceId": "39123c9f8e4749df84b39dfbdafdc800",
    "HashCode": "19FF69BBAD66AA1BFFFAC7183FC4FF21",
    "Message": null,
    "Amount": 50,
    "TransactionAmount": 50,
    "HasAmountMismatch": true,
    "ReceiptUrl": "https://example.com"
}

HasAmountMismatch denotes that we have money transfer from users but different amounts. On this occasion you should consider TransactionAmount as the real transaction amount and ovveride the previous value.

Using TransactionAmount just in case as the source-of-truth is safer and recommended.

If you want to ignore deposits with not matcing prices, we will set your account for automatic cancellation. Please notify our staff to enable the automatic cancellation feature.

Calculating Hash Codes

There is a simple formula.

hashCode = md5(secretKey + amount + referenceId)

If the provided hashcode does not match, the API will reject deposit requests.

Native API

While we recommend using iFrame depositing due to its simple and easy to use experience, some companies prefer hosting their own user interfaces for deposit pages. We support this through our native API.

It is quite a low-level API that is not recommended for most use cases. But if you are a company that wants to have their own deposit pages, this is the way to go.

Methods

Documentation for each method is listed below.

Papara

Fulfilling a papara deposit involves a 2 (at most 3) step process.

  1. Get the customers' papara account email and password. See Papara First Login.
  2. Verify the received 2FA code. See Papara 2FA.
  3. (Optionally) verify the newly created device. See Papara Validate User Device.

Papara First Login

After creating a deposit request using:

curl -X 'POST' \
  'https://grassman.vevopay.io/api/services/app/TransactionRequests/CreateDeposit' \
  -H 'accept: text/plain' \
  -H 'WebApiKey: 5FA6CE55-B9FF-40D0-BFD5-1642D53B3C37' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'X-XSRF-TOKEN: null' \
  -d '{
  "amount": 1,
  "userId": "string",
  "name": "string",
  "username": "string",
  "referenceId": "hello-vevopay-deposit",
  "transactionType": 1,
  "paymentMethod": 1,
  "hashCode": "string"
}'

And acquiring a transactionId, the customer must provide their account's email and password.

  • email: Just a regular email.
  • password: A 6 digit password. Such as 123456.

After getting these values, you need to provide them to our first login endpoint. Here's an examplary curl one-liner:

curl -X 'POST' \
  'https://grassman.vevopay.io/api/services/app/TransactionRequests/PaparaCustomerLogin' \
  -H 'accept: text/plain' \
  -H 'WebApiKey: 5FA6CE55-B9FF-40D0-BFD5-1642D53B3C37' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'X-XSRF-TOKEN: null' \
  -d '{
  "trackingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "userName": "[email protected]",
  "password": "123456"
}'

If the papara account exists and the password is valid, this will return a response like this:

{
  "result": "this will be a JWT",
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

You will want to save the JWT token because we will need it in the next step, 2 factor auth

Papara 2FA

After getting the token from the previous step, an SMS with a code will be sent to the customer. You will want to ask the user for that in this step.

  • tfaCode: A 6 digit verification code received by the customer. Such as 123456.

You can then use these two values to verify the provided 2FA code:

curl -X 'POST' \
  'https://grassman.vevopay.io/api/services/app/TransactionRequests/Papara2Fa' \
  -H 'accept: text/plain' \
  -H 'WebApiKey: 5FA6CE55-B9FF-40D0-BFD5-1642D53B3C37' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'X-XSRF-TOKEN: null' \
  -d '{
  "trackingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": "jwt-token",
  "code": "123456"
}'

If the provided JWT isn't expired and the 2fa code is valid, this will return a response like this:

{
  "result": {
    "next_step": "Completed", // or ValidateUserDevice
    "token": "another JWT",
    "account_number": 123423451
  },
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

There are two paths to take after this depending on the next_step:

  • Completed: we have completed the transaction successfully and deposited the money. There are not more steps left after this and the customer can be redirected back to where he was supposed to be.
  • ValidateUserDevice: See Papara Validate User Device

Papara Validate User Device

After getting the token from the previous step, an email with a device verification button will be sent to the customer. They should verify the newly signed-in device to complete this last step for this deposit to be done.

You can either periodically (every 2 seconds for example) or by asking the customer (via an "I've verified the device" button) check if the device was approved.

An example request for doing so is:

curl -X 'POST' \
  'https://grassman.vevopay.io/api/services/app/TransactionRequests/PaparaValidateUserDevice' \
  -H 'accept: text/plain' \
  -H 'WebApiKey: 5FA6CE55-B9FF-40D0-BFD5-1642D53B3C37' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'X-XSRF-TOKEN: null' \
  -d '{
  "token": "string",
  "trackingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

If the JWT hasn't expired and the customer verified the device, it will return a response like this.

{
  "result": "Completed",
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

At this point the customer deposited the money successfully. You can redirect them at to where they are supposed to be.