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 date-time
Description
An ISO timestamp indicating when the payment request was created
Name
updatedAt
Type
string date-time
Description
An ISO Timestamp indicating when the payment request was last updated

Optional attributes

Name
amount
Type
number float
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, MWK)
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<PaymentRequestProcessorResource>
Description
Required nested attributes (2)
Name
paymentGatewayType
Type
enum(stripe, paypal, adyen, custom, cardconnect, worldline, shift4, authorizenet, wallee, square, payfast, touchnet, transact, unzer, monext, vivenuPayments, ebanx, rapyd, momentusPayments, paymob, additional-payment-method)
Description
Name
createdAt
Type
string date-time
Description
An ISO timestamp indicating when the payment request processor was created
Optional nested attributes (4)
Name
paymentGatewayId
Type
string
Description
Name
reference
Type
string
Description
Name
redirectUrl
Type
string
Description
Name
data
Type
array | boolean | number | object | string
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 date-time
Description
An ISO timestamp indicating when the history entry was added
Optional nested attributes (1)
Name
data
Type
array | boolean | number | object | string
Description
Name
applications
Type
array<object>
Description
Required nested attributes (2)
Name
amount
Type
number float
Description
The amount of the application
Name
method
Type
enum(deposit, customer_balance)
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 email
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 date-time
Description
An ISO timestamp indicating when the payment request will expire and a new one will be created if requested

Example

{
  "_id": "507f191e810c19729de860ea",
  "secret": "4b5fb736-45fd-4895-b497-124a2360c7e6",
  "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": [
    {
      "paymentGatewayType": "stripe",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "paymentGatewayId": "507f191e810c19729de860ea",
      "reference": "string",
      "redirectUrl": "string",
      "data": []
    }
  ],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "random@mail.com",
    "country": "DE"
  },
  "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": "4b5fb736-45fd-4895-b497-124a2360c7e6",
    "checkoutId": "507f191e810c19729de860ea",
    "transactionId": "507f191e810c19729de860ea"
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "secret": "4b5fb736-45fd-4895-b497-124a2360c7e6",
  "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": [
    {
      "paymentGatewayType": "stripe",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "paymentGatewayId": "507f191e810c19729de860ea",
      "reference": "string",
      "redirectUrl": "string",
      "data": []
    }
  ],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "random@mail.com",
    "country": "DE"
  },
  "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
Secret of the payment request

Request

GET

/api/payments/requests/:id

const response = await fetch('https://vivenu.com/api/payments/requests/507f191e810c19729de860ea?secret=4b5fb736-45fd-4895-b497-124a2360c7e6', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "secret": "4b5fb736-45fd-4895-b497-124a2360c7e6",
  "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": [
    {
      "paymentGatewayType": "stripe",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "paymentGatewayId": "507f191e810c19729de860ea",
      "reference": "string",
      "redirectUrl": "string",
      "data": []
    }
  ],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "random@mail.com",
    "country": "DE"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z"
}

GET/api/payments/requests

Get Payment Requests

Query parameters

Optional query parameters

Name
customerId
Type
string
Description
Filter payment requests by customer ID
Name
checkoutId
Type
string
Description
Filter payment requests by checkout ID
Name
status
Type
array<enum(NEW, SUCCEEDED, CANCELED)>
Description
Filter payment requests by status
Name
gatewayId
Type
string
Description
Filter payment requests by gateway ID
Name
origin
Type
array<enum(pos, online, setup, subscription, paymentPlan)>
Description
Filter payment requests by origin
Name
createdAt
Type
object
Description
Range of dates to filter by when the payment request was created in ISO format.
Optional nested attributes (6)
Name
$gt
Type
string date-time
Description
value is greater than
Name
$gte
Type
string date-time
Description
value is greater than or equal
Name
$lt
Type
string date-time
Description
value is less than
Name
$lte
Type
string date-time
Description
value is less than or equal
Name
$eq
Type
string date-time
Description
value is equal
Name
$ne
Type
string date-time
Description
value is not equal
Name
skip
Type
number float
Description
The number of objects to skip for the requested result
Name
top
Type
number float
Description
A limit on the number of objects to be returned. Can range between 1 and 1000.

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": [
    {
      "_id": "507f191e810c19729de860ea",
      "secret": "4b5fb736-45fd-4895-b497-124a2360c7e6",
      "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": [
        {
          "paymentGatewayType": "stripe",
          "createdAt": "2030-01-23T23:00:00.123Z",
          "paymentGatewayId": "507f191e810c19729de860ea",
          "reference": "string",
          "redirectUrl": "string",
          "data": []
        }
      ],
      "history": [
        {
          "type": "payment_request.created",
          "date": "2030-01-23T23:00:00.123Z",
          "data": []
        }
      ],
      "applications": [
        {
          "amount": 10.5,
          "method": "deposit"
        }
      ],
      "customer": {
        "customerId": "507f191e810c19729de860ea",
        "email": "random@mail.com",
        "country": "DE"
      },
      "expiresAt": "2030-01-23T23:00:00.123Z"
    }
  ],
  "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
Name
secret
Type
string
Description
The secret of the payment request

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": "string",
    "secret": "4b5fb736-45fd-4895-b497-124a2360c7e6"
  }),
})

const data = await response.json()

Response (200)

{
  "paymentGatewayType": "stripe",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "paymentGatewayId": "507f191e810c19729de860ea",
  "reference": "string",
  "redirectUrl": "string",
  "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, girocard, 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, interac, customerbalance, unionpay, grabpay, unknown, none)
Description
The payment method used to pay
Name
paymentMethodDetails
Type
object
Description
Payment method details to store as a customer payment method. Only accepted and required for payment requests with origin 'setup'. These details will be stored for future use, and a unique token will be returned that you need to associate with payment method on your side.
Optional nested attributes (3)
Name
identifier
Type
string
Description
Customer-visible label of a payment method, usually last 4 digits of CC number. Do not pass full raw payment credentials. Number sequences longer than 4 characters will be masked.
Name
expirationMonth
Type
integer
Description
Month when the payment method expires, 1-12
Name
expirationYear
Type
integer
Description
Year when the payment method expires, 4 digits
Name
paymentMethodVariant
Type
enum(applepay, googlepay, link)
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",
    "paymentMethodDetails": {
      "identifier": "string",
      "expirationMonth": 1,
      "expirationYear": 1
    },
    "paymentMethodVariant": "applepay"
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "secret": "4b5fb736-45fd-4895-b497-124a2360c7e6",
  "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": [
    {
      "paymentGatewayType": "stripe",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "paymentGatewayId": "507f191e810c19729de860ea",
      "reference": "string",
      "redirectUrl": "string",
      "data": []
    }
  ],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "random@mail.com",
    "country": "DE"
  },
  "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": "4b5fb736-45fd-4895-b497-124a2360c7e6",
  "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": [
    {
      "paymentGatewayType": "stripe",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "paymentGatewayId": "507f191e810c19729de860ea",
      "reference": "string",
      "redirectUrl": "string",
      "data": []
    }
  ],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "random@mail.com",
    "country": "DE"
  },
  "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
array | boolean | number | object | string
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": "4b5fb736-45fd-4895-b497-124a2360c7e6",
  "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": [
    {
      "paymentGatewayType": "stripe",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "paymentGatewayId": "507f191e810c19729de860ea",
      "reference": "string",
      "redirectUrl": "string",
      "data": []
    }
  ],
  "history": [
    {
      "type": "payment_request.created",
      "date": "2030-01-23T23:00:00.123Z",
      "data": []
    }
  ],
  "applications": [
    {
      "amount": 10.5,
      "method": "deposit"
    }
  ],
  "customer": {
    "customerId": "507f191e810c19729de860ea",
    "email": "random@mail.com",
    "country": "DE"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z"
}