Custom Payment Gateway

This guide shows how to connect your own payment gateway to vivenu checkout and refund flows.

Prerequisites

Create a gateway in Payment Gateways.
Copy the gateway secret from The payment gateway object.
Activate the gateway via Update a payment gateway.

Payment flow

Customer selects your gateway in checkout.
Customer is redirected to your gateway UI.
You verify and process the payment.
You confirm or fail the payment request against vivenu.

See the full endpoint details in Payment Requests.

Refund flow

When refunds are enabled, vivenu sends a signed refund request payload to your refund endpoint.

Refund request payload

Required attributes

Name
id
Type
string
Description
A unique ID for the request
Name
time
Type
string
Description
An ISO timestamp of the request. Can be used to prevent old requests from being processed
Name
mode
Type
enum(dev, prod)
Description
Server mode of the API
Name
type
Type
enum(payment.refund)
Description
The type of the action
Name
data
Type
object
Description
Required nested attributes (5)
Name
transactionId
Type
string
Description
The ID of the transaction to refund
Name
sellerId
Type
string
Description
The ID of the seller
Name
psp
Type
string
Description
The reference of the payment
Name
amount
Type
number
Description
The amount to refund
Name
currency
Type
enum(EUR, USD, GBP, AUD, CHF, THB, ILS, COP, MXN, DKK, NOK, SEK, QAR, CAD, ISK, GTQ, INR, DOP, SGD, PLN, SAR, TTD, ZAR, KYD, HKD, CZK, KRW, JPY, NZD, AED, MAD, TWD, BRL, BWP, NAD, KES, SCR, TRY, SZL, LSL, TZS, UGX, ZMW, ZWG, GHS, NGN, SLE, LRD, XOF, XAF, GEL, IDR, ARS, CRC, HUF, EGP, MYR, VND, PHP)
Description
An ISO 4217 3-character code of the currency

Example

{
  "id": "507f191e810c19729de860ea",
  "time": "2030-01-23T23:00:00.123Z",
  "mode": "dev",
  "type": "payment.refund",
  "data": {
    "transactionId": "507f191e810c19729de860ea",
    "sellerId": "507f191e810c19729de860ea",
    "psp": "string",
    "amount": 19.15,
    "currency": "EUR"
  }
}

Verify request signature

Validate x-vivenu-signature by hashing the raw request body with sha256 and your gateway secret.

const signature = crypto
  .createHmac('sha256', GATEWAY_SECRET)
  .update(req.rawPayload)
  .digest('hex')

const requestSignature = req.headers['x-vivenu-signature']
const isValid = signature.toLowerCase() === requestSignature.toLowerCase()