Payment Requests

The Payment Request Object

Required attributes

Name
_id
Type
string
Description
The ID of the payment request
Name
secret
Type
string
Description
The secret token of the payment request
Name
status
Type
enum(NEW, SUCCEEDED, CANCELED)
Description
Name
sellerId
Type
string
Description
Name
createdAt
Type
string
Description
An ISO timestamp indicating when the payment request was created
Name
updatedAt
Type
string
Description
An ISO Timestamp indicating when the payment request was last updated

Optional attributes

Name
amount
Type
number
Description
The amount which needs to be paid
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
Name
checkoutId
Type
string
Description
The ID of the checkout that request belongs to
Name
subscriptionId
Type
string
Description
The ID of the subscription that request belongs to
Name
paymentPlanId
Type
string
Description
The ID of the payment plan that request belongs to
Name
paymentGatewayId
Type
string
Description
The ID of the payment gateway responsible for the payment
Name
reference
Type
string
Description
Name
processors
Type
array<object>
Description
Name
history
Type
array<object>
Description
Required nested attributes (2)
Name
type
Type
enum(payment_request.created, payment_request.details_submitted, payment_request.verified, payment_request.confirmed, payment_request.succeeded, payment_request.canceled)
Description
Name
date
Type
string
Description
An ISO timestamp indicating when the history entry was added
Optional nested attributes (1)
Name
data
Type
oneOf
Description
Name
applications
Type
array<object>
Description
Required nested attributes (2)
Name
amount
Type
number
Description
The amount of the application
Name
method
Type
enum(deposit)
Description
The method of the application
Name
customer
Type
object
Description
Optional nested attributes (3)
Name
customerId
Type
string
Description
The ID of the customer of the payment request
Name
email
Type
string
Description
The email of the user of the payment request
Name
country
Type
string
Description
The country of the user of the payment request
Name
expiresAt
Type
string
Description
An ISO timestamp indicating when the payment request will expire and a new one will be created if requested

Example

{
  "_id": "507f191e810c19729de860ea",
  "secret": "string",
  "status": "NEW",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "amount": 10.5,
  "currency": "EUR",
  "checkoutId": "507f191e810c19729de860ea",
  "subscriptionId": "507f191e810c19729de860ea",
  "paymentPlanId": "507f191e810c19729de860ea",
  "paymentGatewayId": "507f191e810c19729de860ea",
  "reference": "string",
  "processors": [],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "example@vivenu.com",
    "country": "string"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z"
}

POSTPUBLIC/api/payments/requests

Create a Payment Request

Payload

Required attributes

Name
secret
Type
string
Description
The secret of the transaction

Optional attributes

Name
checkoutId
Type
string
Description
The ID of the checkout object to create the payment request
Name
transactionId
Type
string
Description
The ID of the transaction object to create the payment request

Request

POST

/api/payments/requests

const response = await fetch('https://vivenu.com/api/payments/requests', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "secret": "string",
    "checkoutId": "507f191e810c19729de860ea",
    "transactionId": "507f191e810c19729de860ea"
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "secret": "string",
  "status": "NEW",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "amount": 10.5,
  "currency": "EUR",
  "checkoutId": "507f191e810c19729de860ea",
  "subscriptionId": "507f191e810c19729de860ea",
  "paymentPlanId": "507f191e810c19729de860ea",
  "paymentGatewayId": "507f191e810c19729de860ea",
  "reference": "string",
  "processors": [],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "example@vivenu.com",
    "country": "string"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z"
}

GETPUBLIC/api/payments/requests/:id

Get a Payment Request

Query parameters

Optional query parameters

Name
secret
Type
string
Description

Request

GET

/api/payments/requests/:id

const response = await fetch('https://vivenu.com/api/payments/requests/507f191e810c19729de860ea?secret=value', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "secret": "string",
  "status": "NEW",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "amount": 10.5,
  "currency": "EUR",
  "checkoutId": "507f191e810c19729de860ea",
  "subscriptionId": "507f191e810c19729de860ea",
  "paymentPlanId": "507f191e810c19729de860ea",
  "paymentGatewayId": "507f191e810c19729de860ea",
  "reference": "string",
  "processors": [],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "example@vivenu.com",
    "country": "string"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z"
}

GET/api/payments/requests

Get Payment Requests

Query parameters

Optional query parameters

Name
customerId
Type
string
Description
Name
checkoutId
Type
string
Description
Name
status
Type
array<enum(NEW, SUCCEEDED, CANCELED)>
Description
Name
gatewayId
Type
string
Description
Name
origin
Type
array<enum(pos, online, setup, subscription, paymentPlan)>
Description
Name
createdAt
Type
object
Description
Name
skip
Type
number
Description
Name
top
Type
number
Description

Request

GET

/api/payments/requests

const response = await fetch('https://vivenu.com/api/payments/requests?customerId=507f191e810c19729de860ea&checkoutId=507f191e810c19729de860ea&status=value1%2Cvalue2&gatewayId=507f191e810c19729de860ea&origin=value1%2Cvalue2&createdAt=value&skip=10.5&top=10.5', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "docs": [],
  "total": 1
}

POSTPUBLIC/api/payments/requests/:id/processor

Receive Processor Info

Payload

Required attributes

Name
paymentGatewayId
Type
string
Description
The ID of the payment gateway the client intents to use

Optional attributes

Name
returnUrl
Type
string
Description
The URL to return after the user has completed the payment

Request

POST

/api/payments/requests/:id/processor

const response = await fetch('https://vivenu.com/api/payments/requests/507f191e810c19729de860ea/processor', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "paymentGatewayId": "507f191e810c19729de860ea",
    "returnUrl": "https://example.com"
  }),
})

const data = await response.json()

Response (200)

{
  "paymentGatewayType": "stripe",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "paymentGatewayId": "507f191e810c19729de860ea",
  "reference": "string",
  "redirectUrl": "https://example.com",
  "data": []
}

POSTPUBLIC/api/payments/requests/:id/confirm

Confirm a Payment Request

Payload

Required attributes

Name
gatewaySecret
Type
string
Description
The secret of the payment gateway responsible for the payment

Optional attributes

Name
reference
Type
string
Description
A reference to the payment
Name
paymentStatus
Type
enum(SUCCEEDED, PENDING)
Description
The status of the payment
Name
paymentMethod
Type
enum(visa, mc, sepadirectdebit, amex, sofort, klarna, ideal, giropay, paypal, local, discover, custom, twint, postfinance, blik, p24, affirm, dankort, eps, mobilepay, payconiq, bancontact, payfast, distributor, marketplace, cartebancaire, paymentplan, bizum, afterpay, zip, ach, paybybank, link, alipay, wechatpay, pix, eftpos, revolutpay, wero, scalapay, vipps, cashapppay, crypto, unknown, none)
Description
The payment method used to pay
Name
paymentMethodVariant
Type
enum(applepay, googlepay)
Description
The payment variant used to pay

Request

POST

/api/payments/requests/:id/confirm

const response = await fetch('https://vivenu.com/api/payments/requests/507f191e810c19729de860ea/confirm', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "gatewaySecret": "string",
    "reference": "string",
    "paymentStatus": "SUCCEEDED",
    "paymentMethod": "visa",
    "paymentMethodVariant": "applepay"
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "secret": "string",
  "status": "NEW",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "amount": 10.5,
  "currency": "EUR",
  "checkoutId": "507f191e810c19729de860ea",
  "subscriptionId": "507f191e810c19729de860ea",
  "paymentPlanId": "507f191e810c19729de860ea",
  "paymentGatewayId": "507f191e810c19729de860ea",
  "reference": "string",
  "processors": [],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "example@vivenu.com",
    "country": "string"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z"
}

POSTPUBLIC/api/payments/requests/:id/payment-status

Change Payment Request Payment Status

Payload

Required attributes

Name
paymentStatus
Type
enum(SUCCEEDED, FAILED)
Description
The new payment status
Name
gatewaySecret
Type
string
Description
The secret of the payment gateway responsible for the payment

Request

POST

/api/payments/requests/:id/payment-status

const response = await fetch('https://vivenu.com/api/payments/requests/507f191e810c19729de860ea/payment-status', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "paymentStatus": "SUCCEEDED",
    "gatewaySecret": "string"
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "secret": "string",
  "status": "NEW",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "amount": 10.5,
  "currency": "EUR",
  "checkoutId": "507f191e810c19729de860ea",
  "subscriptionId": "507f191e810c19729de860ea",
  "paymentPlanId": "507f191e810c19729de860ea",
  "paymentGatewayId": "507f191e810c19729de860ea",
  "reference": "string",
  "processors": [],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "example@vivenu.com",
    "country": "string"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z"
}

POSTPUBLIC/api/payments/requests/:id/verify

Verify a payment request

Payload

Required attributes

Name
paymentGatewayId
Type
string
Description
The ID of the payment gateway the client intents to use

Optional attributes

Name
data
Type
oneOf
Description
custom data to verify the payment

Request

POST

/api/payments/requests/:id/verify

const response = await fetch('https://vivenu.com/api/payments/requests/507f191e810c19729de860ea/verify', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "paymentGatewayId": "507f191e810c19729de860ea",
    "data": []
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "secret": "string",
  "status": "NEW",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "amount": 10.5,
  "currency": "EUR",
  "checkoutId": "507f191e810c19729de860ea",
  "subscriptionId": "507f191e810c19729de860ea",
  "paymentPlanId": "507f191e810c19729de860ea",
  "paymentGatewayId": "507f191e810c19729de860ea",
  "reference": "string",
  "processors": [],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "example@vivenu.com",
    "country": "string"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z"
}