🔧API Reference

This guide describes all the endpoints, parameters, and responses of the PAY API.

Base URL: https://api-pay.venly.io

1) Create Checkout for a Single Payment

Initiate the checkout process for a single payment by calling the following endpoint:

POST /checkout/sessions

Request Body Parameters

Parameter Type Required Description

Parameter	Type	Required	Description
line_items.price_data.product_data.`name`	string	✅	The name of the product to be displayed to your end-user. Such as “Ring NFT”
line_items.price_data.`unit_amount`	integer	✅	Non-negative integer in cents representing the price of your product.
line_items.price_data.`currency`	string	✅	Three-letter ISO currency code, in uppercase.
line_items.`quantity`	integer	✅	The quantity of products you want to create a checkout for.
`success_url`	string	✅	The URL where your user will be directed in case of successful checkout. (URLs must begin with `http` or `https`)
`cancel_url`	string	✅	The URL where your user will be directed in case they decide to cancel the payment. (URLs must begin with `http` or `https`)
`mode`	string	✅	Only “`payment`” is allowed.
customer.`id`	string	❌	The unique ID of your customer for whom this checkout request is being created.

line_items.price_data.product_data.name

string

✅

The name of the product to be displayed to your end-user. Such as “Ring NFT”

line_items.price_data.unit_amount

integer

✅

Non-negative integer in cents representing the price of your product.

line_items.price_data.currency

string

✅

Three-letter ISO currency code, in uppercase.

line_items.quantity

integer

✅

The quantity of products you want to create a checkout for.

success_url

string

✅

The URL where your user will be directed in case of successful checkout. (URLs must begin with http or https)

cancel_url

string

✅

The URL where your user will be directed in case they decide to cancel the payment. (URLs must begin with http or https)

mode

string

✅

Only “payment” is allowed.

customer.id

string

❌

The unique ID of your customer for whom this checkout request is being created.

Request Body

In this example, we are creating a checkout link for one Ring NFT with a value of €20. We have also specified the success and cancel URLs.

{
  "line_items": [
    {
      "price_data": {
        "product_data": {
          "name": "Ring NFT"
        },
        "unit_amount": 2000,
        "currency": "EUR"
      },
      "quantity": 1
    }
  ],
  "success_url": "https://www.venly.io/",
  "cancel_url": "https://www.venly.io/",
  "mode": "payment"
}

Response Body

Save the following parameters from response body:

id : This parameter is the sessionId (Used when checking status of this checkout)
url : This parameter is the checkout URL (You pass this to your end-user)

{
    "id": "cs_test_a1tpJvmnmcQtoBZmIR9jsTLNg07T8N6OgPLPdYJ9uwiE6I9JQqEcEmFFUf",
    "object": "checkout.session",
    "after_expiration": null,
    "allow_promotion_codes": null,
    "amount_subtotal": 2000,
    "amount_total": 2000,
    "automatic_tax": {
        "enabled": false,
        "status": null
    },
    "billing_address_collection": null,
    "cancel_url": "https://www.venly.io/",
    "client_reference_id": null,
    "consent": null,
    "consent_collection": null,
    "created": 1692785133,
    "currency": "eur",
    "currency_conversion": null,
    "custom_fields": [],
    "custom_text": {
        "shipping_address": null,
        "submit": null
    },
    "customer": null,
    "customer_creation": "if_required",
    "customer_details": null,
    "customer_email": null,
    "expires_at": 1692871532,
    "invoice": null,
    "invoice_creation": {
        "enabled": false,
        "invoice_data": {
            "account_tax_ids": null,
            "custom_fields": null,
            "description": null,
            "footer": null,
            "metadata": {},
            "rendering_options": null
        }
    },
    "livemode": false,
    "locale": null,
    "metadata": {},
    "mode": "payment",
    "payment_intent": null,
    "payment_link": null,
    "payment_method_collection": "always",
    "payment_method_options": {},
    "payment_method_types": [
        "card"
    ],
    "payment_status": "unpaid",
    "phone_number_collection": {
        "enabled": false
    },
    "recovered_from": null,
    "setup_intent": null,
    "shipping_address_collection": null,
    "shipping_cost": null,
    "shipping_details": null,
    "shipping_options": [],
    "status": "open",
    "submit_type": null,
    "subscription": null,
    "success_url": "https://www.venly.io/",
    "total_details": {
        "amount_discount": 0,
        "amount_shipping": 0,
        "amount_tax": 0
    },
    "url": "https://checkout.stripe.com/c/pay/cs_test_a1tpJvmnmcQtoBZmIR9jsTLNg07T8N6OgPLPdYJ9uwiE6I9JQqEcEmFFUf#fid2cXdsdWBEZmZqcGtxJz8nZGZmcVo0S21cUGRGVmR%2FNUAxZEFyJyknZHVsTmB8Jz8ndW5acWB2cVowNE10Z3BQQ2FnSmxpVFVsX19gRFxATGZdTmZGTD18NHBmdktycDEydzFLbjx1VVVjSFJGYH9WcVJ9SjdcUG1mYk1qXWs0SVZ8M1VPcUEzZkRyV39IfFxVSzU1b1BIYG88M30nKSdjd2poVmB3c2B3Jz9xd3BgKSdpZHxqcHFRfHVgJz8ndmxrYmlgWmxxYGgnKSdga2RnaWBVaWRmYG1qaWFgd3YnP3F3cGB4JSUl"
}

Click here to read Stripe documentation for this endpoint.

2) Check Status of a Checkout

To retrieve the details of a completed or canceled checkout, call this endpoint using the corresponding session ID:

GET /checkout/sessions/{sessionId}

Path Parameter

{sessionId} : This is the session ID to check the status of a specific checkout payment. It’s in the response body when you create a checkout link.

Response Body

Look for the following parameters in the response body:

Parameter Possible Values & Description

Parameter	Possible Values & Description
`payment_status`	paid: The payment funds are available in your account. unpaid: The payment funds are not yet available in your account.
`status`	open: The checkout session is still in progress. Payment processing has not started. complete: The checkout session is complete. Payment processing may still be in progress. expired: The checkout session has expired. No further processing will occur.
`payment_intent`	The `payment_intent` object represents the actual payment transaction that needs to take place. It includes details about the amount, currency, payment method, etc.
`amount_total`	The total sum of all items, factoring in applied discounts and taxes.
`payment_link`	The `payment_link` object includes the checkout URL, data about the products being sold, and indicates whether the payment link’s URL is active.

payment_status

paid: The payment funds are available in your account.
unpaid: The payment funds are not yet available in your account.

status

open: The checkout session is still in progress. Payment processing has not started.
complete: The checkout session is complete. Payment processing may still be in progress.
expired: The checkout session has expired. No further processing will occur.

payment_intent

The payment_intent object represents the actual payment transaction that needs to take place. It includes details about the amount, currency, payment method, etc.

amount_total

The total sum of all items, factoring in applied discounts and taxes.

payment_link

The payment_link object includes the checkout URL, data about the products being sold, and indicates whether the payment link’s URL is active.

{
    "id": "cs_test_a1cLJATpwDr0N5nfKSIk3VJDKMcEtOMGIZNwWf5nZ2v1EivlO6wIK5gY0f",
    "object": "checkout.session",
    "after_expiration": null,
    "allow_promotion_codes": null,
    "amount_subtotal": 2000,
    "amount_total": 2000,
    "automatic_tax": {
        "enabled": false,
        "status": null
    },
    "billing_address_collection": null,
    "cancel_url": "https://www.venly.io/",
    "client_reference_id": null,
    "consent": null,
    "consent_collection": null,
    "created": 1692750644,
    "currency": "eur",
    "currency_conversion": null,
    "custom_fields": [],
    "custom_text": {
        "shipping_address": null,
        "submit": null
    },
    "customer": null,
    "customer_creation": "if_required",
    "customer_details": {
        "address": {
            "city": null,
            "country": "PK",
            "line1": null,
            "line2": null,
            "postal_code": null,
            "state": null
        },
        "email": "test@gmail.com",
        "name": "Stripe",
        "phone": null,
        "tax_exempt": "none",
        "tax_ids": []
    },
    "customer_email": null,
    "expires_at": 1692837044,
    "invoice": null,
    "invoice_creation": {
        "enabled": false,
        "invoice_data": {
            "account_tax_ids": null,
            "custom_fields": null,
            "description": null,
            "footer": null,
            "metadata": {},
            "rendering_options": null
        }
    },
    "livemode": false,
    "locale": null,
    "metadata": {},
    "mode": "payment",
    "payment_intent": "pi_3Ni59PCSaz0E4aDw1hw6eAnw",
    "payment_link": null,
    "payment_method_collection": "always",
    "payment_method_options": {},
    "payment_method_types": [
        "card"
    ],
    "payment_status": "paid",
    "phone_number_collection": {
        "enabled": false
    },
    "recovered_from": null,
    "setup_intent": null,
    "shipping_address_collection": null,
    "shipping_cost": null,
    "shipping_details": null,
    "shipping_options": [],
    "status": "complete",
    "submit_type": null,
    "subscription": null,
    "success_url": "https://www.venly.io/",
    "total_details": {
        "amount_discount": 0,
        "amount_shipping": 0,
        "amount_tax": 0
    },
    "url": null
}

Click here to read Stripe documentation for this endpoint.

3) Fetch Stripe Dashboard

This endpoint allows you to fetch a login link for your Stripe dashboard:

GET /stripe-dashboard

Response

The API will provide the login URL as a response. Copy and paste this link into a web browser to gain access to your Stripe dashboard. Here you can get an overview of all the transactions.

{
    "object": "login_link",
    "created": 1692784524,
    "url": "https://connect.stripe.com/express/acct_1oJl3NhYUE4aDw/jy9JOia7aCSaz0"
}

4) Customize Branding for Checkout Page

You can customize the checkout page by incorporating your business logo and chosen color scheme.

4.1) Upload icon

Personalize your checkout page by adding your business' icon or logo. To begin, upload your chosen icon.

The icon must be a square image and have a minimum size of 128px x 128px.

Endpoint:

POST /account/settings/branding/icon

Request Body

Parameter Type Description Request Type

Parameter	Type	Description	Request Type
`icon`	File	A square icon image with a minimum size of 128px x 128px.	multipart/form-data

icon

File

A square icon image with a minimum size of 128px x 128px.

multipart/form-data

Response Body

Save the first id field. This is the icon ID, and will be used when customizing the checkout page.

{
    "id": "file_1Nk6WcFdbOilQPiZLgnem6MT",
    "object": "file",
    "created": 1693233282,
    "expires_at": null,
    "filename": "icon5243171464818044029venly logo.jpg",
    "links": {
        "object": "list",
        "data": [],
        "has_more": false,
        "url": "/v1/file_links?file=file_1Nk6WcFdbOilQPiZLgnem6MT"
    },
    "purpose": "business_icon",
    "size": 9231,
    "title": null,
    "type": "jpg",
    "url": "https://files.stripe.com/v1/files/file_1Nk6WcFdbOilQPiZLgnem6MT/contents"
}

4.2) Customize the checkout page

You can select a primary color for the left side of the checkout page, and a secondary color for the PAY button. The checkout page will also feature your icon.

Endpoint:

POST /account/settings/branding

Request Body Parameters

Parameter Type Required Description

Parameter	Type	Required	Description
settings.branding.`primary_color`	string	✅	A color hex code to customize your checkout page.
settings.branding.`secondary_color`	string	✅	A color hex code to customize the PAY button.
settings.branding.`icon`	string	✅	This is the `id` of your previously uploaded icon. You can find it in the previous endpoint’s response body.

settings.branding.primary_color

string

✅

A color hex code to customize your checkout page.

settings.branding.secondary_color

string

✅

A color hex code to customize the PAY button.

settings.branding.icon

string

✅

This is the id of your previously uploaded icon. You can find it in the previous endpoint’s response body.

Click here to read Stripe documentation for this endpoint.

Example Request

In this example, we will customize the checkout URL with following properties:

Primary Color: Bright Purple (#BF40BF)
Secondary Color: Black (#000000)
Icon: Icon ID from the response of the upload icon endpoint.

POST /account/settings/branding

{
  "settings": {
    "branding": {
      "primary_color": "#BF40BF", 
      "secondary_color": "#000000",
      "icon": "file_1Nk6WcFdbOilQPiZLgnem6MT"
    }
  }
}

Customized Checkout URL Preview

The logo is evident on the top. The primary color is applied on the left side, while the secondary color is applied on the Pay button.

5) Configuring Webhooks/Notifications

You can register your endpoint which allows you to get notifications whenever your end-user makes a successful payment or declines/cancels payment. You can subscribe to a webhook to receive updates of your user's payments.

POST /webhooks

Request Body Parameters

Parameter Type Required Description & Possible Values

Parameter	Type	Required	Description & Possible Values
`url`	string	✅	This is your endpoint URL which can accept `POST` calls.
`application`	string	✅	This can only have the value `PAY`.
authenticationMethod.`type`	string	✅	We allow two types: `BASIC_AUTHENTICATION` `API_KEY`
authenticationMethod.`username`	string	(Required only when `type` is `BASIC_AUTHENTICATION`)	This is the username for your endpoint.
authenticationMethod.`password`	string	(Required only when `type` is `BASIC_AUTHENTICATION`)	This is the password for your endpoint.
authenticationMethod.`headerName`	string	(Used only when `type` is `API_KEY`)	This is the name of your api key.
authenticationMethod.`apiKey`	string	(Used only when `type` is `API_KEY`)	This is the value of api key for your endpoint.

url

string

✅

This is your endpoint URL which can accept POST calls.

application

string

✅

This can only have the value PAY.

authenticationMethod.type

string

✅

We allow two types:

BASIC_AUTHENTICATION
API_KEY

authenticationMethod.username

string

(Required only when type is BASIC_AUTHENTICATION)

This is the username for your endpoint.

authenticationMethod.password

string

(Required only when type is BASIC_AUTHENTICATION)

This is the password for your endpoint.

authenticationMethod.headerName

string

(Used only when type is API_KEY)

This is the name of your api key.

authenticationMethod.apiKey

string

(Used only when type is API_KEY)

This is the value of api key for your endpoint.

Click here to view Stripe documentation for events.

Example Request with authentication method: `BASIC_AUTHENTICATION`

POST /webhooks

{
  "url": "https://example.endpoint.com",
  "application": "PAY",
  "authenticationMethod": 
    {
      "type": "BASIC_AUTHENTICATION",
      "username": "your_username_here",
      "password": "your_password_here"
    }
}

Example Request with authentication method: `API_KEY`

POST /webhooks

{
  "url": "https://example.endpoint.com",
  "application": "PAY",
  "authenticationMethod": 
    {
      "type": "API_KEY",
       "headerName": "header_name_here",
       "apiKey": "your_api_key"
    }
}

PreviousExample Scenario NextGuides

Last updated 6 months ago

1) Create Checkout for a Single Payment

POST /checkout/sessions

Request Body Parameters

Request Body

Response Body

2) Check Status of a Checkout

GET /checkout/sessions/{sessionId}

Response Body

3) Fetch Stripe Dashboard

GET /stripe-dashboard

Response

4) Customize Branding for Checkout Page

4.1) Upload icon

POST /account/settings/branding/icon

Request Body

Response Body

4.2) Customize the checkout page

POST /account/settings/branding

Request Body Parameters

Example Request

POST /account/settings/branding

Customized Checkout URL Preview

5) Configuring Webhooks/Notifications

POST /webhooks

Request Body Parameters

Example Request with authentication method: BASIC_AUTHENTICATION

POST /webhooks

Example Request with authentication method: API_KEY

POST /webhooks

Example Request with authentication method: `BASIC_AUTHENTICATION`

Example Request with authentication method: `API_KEY`