Templating

Checkout templates pre-define the field visibility and layout for the customer data collection form on the hosted payment page. Once created, apply a template to a checkout session by passing its id in the checkout_template_id field when calling POST /v2/checkout.

Templates have a status of either ACTIVE or INACTIVE. Only ACTIVE templates can be applied to checkout sessions.

How It Works

1

Create a template

Call POST /v2/template/checkoutDetails with your desired field configuration. The response includes the assigned id — store this for use when creating checkouts.

2

Apply to a checkout

Pass the template id as checkout_template_id in the POST /v2/checkout request body. See Checkout Sessions.

3

Update or deactivate as needed

Use PATCH /v2/template/checkoutDetails/{id} to modify an existing template, or DELETE /v2/template/checkoutDetails/{id} to remove it.

API Reference

Create Template

Create Template

post

/v2/template/checkoutDetails

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Body

namestring · max: 255Required

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

billing_is_same_as_shippingbooleanOptional

Indicates whether billing address is same as shipping address or not.

Default: true

shipping_first_billing_secondbooleanOptional

Indicates the order of addresses in which the merchant wants to collect the information from the customer.

Default: false

Responses

200

Successful

application/json

namestring · max: 255Required

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

billing_is_same_as_shippingbooleanOptional

Indicates whether billing address is same as shipping address or not.

Default: true

shipping_first_billing_secondbooleanOptional

Indicates the order of addresses in which the merchant wants to collect the information from the customer.

Default: false

idstringOptional

created_atstring · dateOptional

updated_atstring · dateOptional

statusstring · enumOptional

Indicates whether the template is active or not.

Possible values:

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

post/v2/template/checkoutDetails

POST /oidc/checkout-service/v2/template/checkoutDetails HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 1075

{
  "name": "text",
  "entity_id": "text",
  "billing_is_same_as_shipping": true,
  "shipping_first_billing_second": false,
  "field_settings": {
    "billing": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "company_name": {
      "mode": "HIDDEN"
    },
    "company_registration_number": {
      "mode": "HIDDEN"
    },
    "email_address": {
      "mode": "HIDDEN"
    },
    "entity_id": {
      "mode": "HIDDEN"
    },
    "phone_number": {
      "mode": "HIDDEN"
    },
    "shipping": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "title": {
      "mode": "HIDDEN"
    },
    "work_phone": {
      "mode": "HIDDEN"
    },
    "tax": {
      "identifier": {
        "mode": "HIDDEN"
      }
    }
  }
}

{
  "name": "text",
  "entity_id": "text",
  "billing_is_same_as_shipping": true,
  "shipping_first_billing_second": false,
  "field_settings": {
    "billing": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "company_name": {
      "mode": "HIDDEN"
    },
    "company_registration_number": {
      "mode": "HIDDEN"
    },
    "email_address": {
      "mode": "HIDDEN"
    },
    "entity_id": {
      "mode": "HIDDEN"
    },
    "phone_number": {
      "mode": "HIDDEN"
    },
    "shipping": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "title": {
      "mode": "HIDDEN"
    },
    "work_phone": {
      "mode": "HIDDEN"
    },
    "tax": {
      "identifier": {
        "mode": "HIDDEN"
      }
    }
  },
  "id": "text",
  "created_at": "2026-01-01",
  "updated_at": "2026-01-01",
  "status": "ACTIVE"
}

List Templates

List Templates

get

/v2/template/checkoutDetails/

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Query parameters

searchstringOptional

Filter templates using RSQL syntax. Combine expressions with ; (AND) or , (OR).

Filterable fields:

Field	Type	Operators
name	string	== != =in= =out= =regex= =contains=
created_at	date	== != =in= =out= =gt= =ge= =lt= =le=
updated_at	date	== != =in= =out= =gt= =ge= =lt= =le=
entity_id	string	== != =in= =out= =regex=

Examples:

• name==MyTemplate;entity_id==a6b45428-0296-4394-8ddd-0b50b5b20aa9
• name==TemplateName

order_criteriastring · enumOptionalPossible values:

order_bystring · enumOptional

The ordering sequence of the selected templates If not selected then Descending order is the default order.

Possible values:

page_numbernumber · min: 1Optional

A filter query in RSQL format to retrieve templates based on page number. If not selected then a default pageNumber is 1.

page_sizenumberOptional

A filter query in RSQL format to retrieve templates based on page size. If not selected then a default pageSize is 50

Responses

200

Successful

application/json

namestring · max: 255Required

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

billing_is_same_as_shippingbooleanOptional

Indicates whether billing address is same as shipping address or not.

Default: true

shipping_first_billing_secondbooleanOptional

Indicates the order of addresses in which the merchant wants to collect the information from the customer.

Default: false

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get/v2/template/checkoutDetails/

GET /oidc/checkout-service/v2/template/checkoutDetails/ HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

[
  {
    "name": "text",
    "entity_id": "text",
    "billing_is_same_as_shipping": true,
    "shipping_first_billing_second": false,
    "field_settings": {
      "billing": {
        "address_1": {
          "mode": "HIDDEN"
        },
        "address_2": {
          "mode": "HIDDEN"
        },
        "address_3": {
          "mode": "HIDDEN"
        },
        "city": {
          "mode": "HIDDEN"
        },
        "country_code": {
          "mode": "HIDDEN"
        },
        "first_name": {
          "mode": "HIDDEN"
        },
        "middle_name": {
          "mode": "HIDDEN"
        },
        "last_name": {
          "mode": "HIDDEN"
        },
        "phone": {
          "mode": "HIDDEN"
        },
        "postal_code": {
          "mode": "HIDDEN"
        },
        "state": {
          "mode": "HIDDEN"
        }
      },
      "company_name": {
        "mode": "HIDDEN"
      },
      "company_registration_number": {
        "mode": "HIDDEN"
      },
      "email_address": {
        "mode": "HIDDEN"
      },
      "entity_id": {
        "mode": "HIDDEN"
      },
      "phone_number": {
        "mode": "HIDDEN"
      },
      "shipping": {
        "address_1": {
          "mode": "HIDDEN"
        },
        "address_2": {
          "mode": "HIDDEN"
        },
        "address_3": {
          "mode": "HIDDEN"
        },
        "city": {
          "mode": "HIDDEN"
        },
        "country_code": {
          "mode": "HIDDEN"
        },
        "first_name": {
          "mode": "HIDDEN"
        },
        "middle_name": {
          "mode": "HIDDEN"
        },
        "last_name": {
          "mode": "HIDDEN"
        },
        "phone": {
          "mode": "HIDDEN"
        },
        "postal_code": {
          "mode": "HIDDEN"
        },
        "state": {
          "mode": "HIDDEN"
        }
      },
      "title": {
        "mode": "HIDDEN"
      },
      "work_phone": {
        "mode": "HIDDEN"
      },
      "tax": {
        "identifier": {
          "mode": "HIDDEN"
        }
      }
    }
  }
]

Get a templates by ID

Get a template by id

get

/v2/template/checkoutDetails/{id}

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Path parameters

idstringRequired

The id parameter in the GET API uniquely identifies a checkout template, allowing you to retrieve detailed information about a specific template by providing its associated identifier.

Responses

200

Successful

application/json

namestring · max: 255Required

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

billing_is_same_as_shippingbooleanOptional

Indicates whether billing address is same as shipping address or not.

Default: true

shipping_first_billing_secondbooleanOptional

Indicates the order of addresses in which the merchant wants to collect the information from the customer.

Default: false

idstringOptional

created_atstring · dateOptional

updated_atstring · dateOptional

statusstring · enumOptional

Indicates whether the template is active or not.

Possible values:

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get/v2/template/checkoutDetails/{id}

GET /oidc/checkout-service/v2/template/checkoutDetails/{id} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

{
  "name": "text",
  "entity_id": "text",
  "billing_is_same_as_shipping": true,
  "shipping_first_billing_second": false,
  "field_settings": {
    "billing": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "company_name": {
      "mode": "HIDDEN"
    },
    "company_registration_number": {
      "mode": "HIDDEN"
    },
    "email_address": {
      "mode": "HIDDEN"
    },
    "entity_id": {
      "mode": "HIDDEN"
    },
    "phone_number": {
      "mode": "HIDDEN"
    },
    "shipping": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "title": {
      "mode": "HIDDEN"
    },
    "work_phone": {
      "mode": "HIDDEN"
    },
    "tax": {
      "identifier": {
        "mode": "HIDDEN"
      }
    }
  },
  "id": "text",
  "created_at": "2026-01-01",
  "updated_at": "2026-01-01",
  "status": "ACTIVE"
}

Update Template

Update Template

patch

/v2/template/checkoutDetails/{id}

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Path parameters

idstringRequired

The id parameter in the GET API uniquely identifies a checkout template, allowing you to retrieve detailed information about a specific template by providing its associated identifier.

Body

namestring · max: 255Required

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

billing_is_same_as_shippingbooleanOptional

Indicates whether billing address is same as shipping address or not.

Default: true

shipping_first_billing_secondbooleanOptional

Indicates the order of addresses in which the merchant wants to collect the information from the customer.

Default: false

Responses

200

Successful

application/json

namestring · max: 255Required

entity_idstringOptional

Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)

billing_is_same_as_shippingbooleanOptional

Indicates whether billing address is same as shipping address or not.

Default: true

shipping_first_billing_secondbooleanOptional

Indicates the order of addresses in which the merchant wants to collect the information from the customer.

Default: false

idstringOptional

created_atstring · dateOptional

updated_atstring · dateOptional

statusstring · enumOptional

Indicates whether the template is active or not.

Possible values:

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

patch/v2/template/checkoutDetails/{id}

PATCH /oidc/checkout-service/v2/template/checkoutDetails/{id} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 1075

{
  "name": "text",
  "entity_id": "text",
  "billing_is_same_as_shipping": true,
  "shipping_first_billing_second": false,
  "field_settings": {
    "billing": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "company_name": {
      "mode": "HIDDEN"
    },
    "company_registration_number": {
      "mode": "HIDDEN"
    },
    "email_address": {
      "mode": "HIDDEN"
    },
    "entity_id": {
      "mode": "HIDDEN"
    },
    "phone_number": {
      "mode": "HIDDEN"
    },
    "shipping": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "title": {
      "mode": "HIDDEN"
    },
    "work_phone": {
      "mode": "HIDDEN"
    },
    "tax": {
      "identifier": {
        "mode": "HIDDEN"
      }
    }
  }
}

{
  "name": "text",
  "entity_id": "text",
  "billing_is_same_as_shipping": true,
  "shipping_first_billing_second": false,
  "field_settings": {
    "billing": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "company_name": {
      "mode": "HIDDEN"
    },
    "company_registration_number": {
      "mode": "HIDDEN"
    },
    "email_address": {
      "mode": "HIDDEN"
    },
    "entity_id": {
      "mode": "HIDDEN"
    },
    "phone_number": {
      "mode": "HIDDEN"
    },
    "shipping": {
      "address_1": {
        "mode": "HIDDEN"
      },
      "address_2": {
        "mode": "HIDDEN"
      },
      "address_3": {
        "mode": "HIDDEN"
      },
      "city": {
        "mode": "HIDDEN"
      },
      "country_code": {
        "mode": "HIDDEN"
      },
      "first_name": {
        "mode": "HIDDEN"
      },
      "middle_name": {
        "mode": "HIDDEN"
      },
      "last_name": {
        "mode": "HIDDEN"
      },
      "phone": {
        "mode": "HIDDEN"
      },
      "postal_code": {
        "mode": "HIDDEN"
      },
      "state": {
        "mode": "HIDDEN"
      }
    },
    "title": {
      "mode": "HIDDEN"
    },
    "work_phone": {
      "mode": "HIDDEN"
    },
    "tax": {
      "identifier": {
        "mode": "HIDDEN"
      }
    }
  },
  "id": "text",
  "created_at": "2026-01-01",
  "updated_at": "2026-01-01",
  "status": "ACTIVE"
}

Deleting a template is irreversible. Checkouts that referenced the deleted template will not be affected retroactively, but you will no longer be able to apply the template to new sessions.

Delete a template by ID

Delete a template by id

delete

/v2/template/checkoutDetails/{id}

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Path parameters

idstringRequired

The id parameter in the GET API uniquely identifies a checkout template, allowing you to retrieve detailed information about a specific template by providing its associated identifier.

Responses

204

Success. Template was successfully deleted.

No content

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

delete/v2/template/checkoutDetails/{id}

DELETE /oidc/checkout-service/v2/template/checkoutDetails/{id} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

No content

Count Templates

Count Templates

get

/v2/template/checkoutDetails/count

Authorizations

AuthorizationstringRequired

HTTP Basic authentication using entity credentials (username:password encoded in Base64).

Query parameters

searchstringRequired

Filter templates using RSQL syntax. Combine expressions with ; (AND) or , (OR).

Filterable fields:

Field	Type	Operators
name	string	== != =in= =out= =regex= =contains=
created_at	date	== != =in= =out= =gt= =ge= =lt= =le=
updated_at	date	== != =in= =out= =gt= =ge= =lt= =le=
entity_id	string	== != =in= =out= =regex=

Examples:

• name==MyTemplate;entity_id==a6b45428-0296-4394-8ddd-0b50b5b20aa9
• name==TemplateName

Responses

200

Successful

application/json

countnumberOptional

Count

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get/v2/template/checkoutDetails/count

GET /oidc/checkout-service/v2/template/checkoutDetails/count?search=text HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

{
  "count": 1
}