Create a Payment Request

POST /v1/requests

Creates an invoice for a customer to pay.

Request

application/json

Body

required

branding

object

Details on branding elements to apply when rendering the Payment Request page.

icon stringnullable

A secure URL to an image icon

logo stringnullable

A secure URL to an image logo

use_logo boolean

Has the value of true if logo should be rendered in payment page or false if icon should be used.

primary_color stringnullable

A hex color code that will be used as background color of the Payment Request page

secondary_color stringnullable

A hex color code that will be used as background color of the submit or PAY button

currency stringrequired

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customer stringrequired

The ID of the customer who will receive the Payment Request.

delivery_methods string[]required

Possible values: [email, sms]

The methods by which the customer will receive the Payment Request.

line_items

LineItemSerializer[]

required

A list of items the customer will be billed for.

Array [

amount integerrequired

Unit amount of the product in cents represented as a whole integer.

description stringnullable

A description of the product

image stringnullable

A secure URL to an image of the product

name stringrequired

The name of the product

quantity integerrequired

The quantity of the products being purchased

]

message stringnullable

A custom message to be included in the Payment Request.

metadata

object

A set of key-value pairs that you can attach to the Payment Request. It can be useful for storing additional information about the invoice in a structured format.

property name* string

payment_method_types PaymentMethodType (string)[]required

Possible values: [card, bpi, gcash, paymaya, alipay, unionpay, wechat]

The payment methods that are available for the customer to pay the Payment Request.

require_auth boolean

Default value: true

Indicates whether 3D Secure authentication shall be required for card payments. Always have a value true.

Responses

Created

application/json

Schema
Example (from schema)

Schema

id string

The unique identifier of the Payment Request.

object string

String representing the object's type. Objects of the same type share the same value.

account_name string

The name of the merchant who created the Payment Request.

account_support_email stringnullable

The support email of the merchant who created the Payment Request.

branding

object

Details on branding elements to apply when rendering the Payment Request page.

icon stringnullable

A secure URL to an image icon

logo stringnullable

A secure URL to an image logo

use_logo boolean

Has the value of true if logo should be rendered in payment page or false if icon should be used.

primary_color stringnullable

A hex color code that will be used as background color of the Payment Request page

secondary_color stringnullable

A hex color code that will be used as background color of the submit or PAY button

created timestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

currency string

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customer string

The ID of the customer who will receive the Payment Request.

customer_name string

The name of the customer .

customer_phone stringnullable

The phone number of the customer.

delivery_methods string[]

The methods by which the customer will receive the Payment Request.

delivered

object

Indicates the status whether the Payment Request has been delivered to the customer.

email boolean

Indicates the status whether the Payment Request has been delivered to the customer via email.

sms boolean

Indicates the status whether the Payment Request has been delivered to the customer via SMS.

line_items

LineItemSerializer[]

A list of items the customer will be billed for.

Array [

amount integerrequired

Unit amount of the product in cents represented as a whole integer.

description stringnullable

A description of the product

image stringnullable

A secure URL to an image of the product

name stringrequired

The name of the product

quantity integerrequired

The quantity of the products being purchased

]

livemode boolean

Has the value of true if the object exists in live mode or the value of false if the object exists in test mode.

message stringnullable

A custom message to be included in the Payment Request.

metadata

object

A set of key-value pairs that you can attach to the Payment Request. It can be useful for storing additional information about the invoice in a structured format.

property name* string

number string

A unique, identifying string that follows a specific pattern. It is used to identify the Payment Request associated to a customer.

paid boolean

Indicates the status whether the Payment Request has been paid by the customer.

paid_at timestampnullable

Time at which the Payment Request was paid. Measured in seconds since the Unix epoch.

payment_details objectnullable

The charge object details associated with the Payment Request after successful payment.

payment_method_types PaymentMethodType (string)[]

Possible values: [card, bpi, gcash, paymaya, alipay, unionpay, wechat]

The payment methods that are available for the customer to pay the Payment Request.

payment_request_url string

The URL where the customer can view and pay the Payment Request.

require_auth boolean

Default value: true

Indicates whether 3D Secure authentication shall be required for card payments. Always have a value true.

subtotal integer

The total amount of the Payment Request before any discounts or taxes are applied.

total integer

The total amount of the Payment Request after any discounts or taxes are applied.

updated timestamp

Time at which the object was last updated. Measured in seconds since the Unix epoch.

voided boolean

Indicates the status whether the Payment Request has been voided by the merchant.

voided_at timestampnullable

Time at which the Payment Request was voided. Measured in seconds since the Unix epoch.

void_reason stringnullable

The reason provided by the Merchant why the Payment Request was voided.

{
  "id": "pr_017b996e4a6a9cea9562902021febc6b",
  "object": "string",
  "account_name": "Zip Fitness",
  "account_support_email": "[email protected]",
  "branding": {
    "icon": "https://example.com/icon.png",
    "logo": "https://example.com/logo.png",
    "use_logo": true,
    "primary_color": "#FFFFFF",
    "secondary_color": "#4f99fe"
  },
  "created": 1616425200,
  "currency": "PHP",
  "customer": "cus_017b996e4a6a9cea9562902021febc6b",
  "customer_name": "Gerry Isaac",
  "customer_phone": "+639123456789",
  "delivery_methods": [
    "email",
    "sms"
  ],
  "delivered": {
    "email": true,
    "sms": false
  },
  "line_items": [
    {
      "amount": 4999,
      "description": "Annual Fee",
      "image": "string",
      "name": "Zip Elite Membership",
      "quantity": 1
    }
  ],
  "livemode": true,
  "message": "Thank you for continuing your membership!",
  "metadata": {
    "Member ID": "123456"
  },
  "number": "EDE58F9E-0001",
  "paid": false,
  "paid_at": null,
  "payment_details": null,
  "payment_method_types": [
    "card",
    "gcash",
    "paymaya"
  ],
  "payment_request_url": "https://request.zip.ph/pr_017b996e4a6a9cea9562902021febc6b",
  "require_auth": true,
  "subtotal": 4999,
  "total": 4999,
  "updated": 1616425200,
  "voided": false,
  "voided_at": null,
  "void_reason": null
}

Bad request

application/json

Schema
Example (from schema)

Schema

message Error message (string)

error

object

type Error type (string)

message Error message (string)

{
  "message": "Missing parameter: customer",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing parameter: customer"
  }
}

Create a Payment Request

/v1/requests

Request​

Body

Responses​

Request

Responses