Unpaid Invoice Payment Intent Request Generation API

Unpaid Invoice Payment Intent Request Generation API Endpoint

Unpaid Invoice Payment Intent Request Generation API

This endpoint generates a payment intent request for unpaid invoice using invoice ID and facilitates seamless integration with various payment gateways based on the invoice ID. It returns the payment intent along with UI-related keys for loading the respective payment gateway (e.g., Stripe, Lyra, Brain Tree). The response includes comprehensive details for setting up the payment gateway form, incorporating necessary UI integration elements. These details encompass client information, business specifics of the storage center, and property information associated with the invoice. In the case of multiple payment gateway options configured for the specific property, the endpoint returns the one associated with the property's default payment gateway. The property data.paymentGateway will return the key of the payment gateway, and based on this key, information will exist in the response payload.

Stripe

Public Key: data.publicKey
Payment Intent: data.terminalPaymentSecretId
Language LCID Code: data.languageLCIDCode

Usage for Stripe: This endpoint will return the public key, payment intent, and language LCID code. Use these values to load the Stripe payment form.

Lyra

Public Key (kr-public-key): data.publicKey
Form Token (kr-form-token): data.terminalPaymentSecretId
Language LCID Code (kr-language): data.languageLCIDCode

Usage for Lyra: This endpoint will return the public key, KR form token, and language LCID code. Use these values to load the Lyra payment form.

Brain Tree

Authorization Client Token: data.terminalPaymentSecretId
Language LCID Code: data.languageLCIDCode

Usage for Brain Tree: This endpoint will return the authorization client token and language LCID code. Use these values to load the Brain Tree drop-in payment form.

GET

/v1/invoice/{id}/payment

Request Content Type

application/json

Response Content Type

application/json

Request Header

Authorization: X-API-Key string required

X-API-Key is a string of letters and numbers used to authenticate and control access to the API. It can be generated in the StoRegister management application.
Authorization: X-Token string required

X-Token represents the user session token. It is a string of characters that uniquely identifies the user's session.

URL Query Parameters:

id string required

id refers to a ID of the specific unpaid invoice.

Response Payload:

succeeded boolean

Indicates whether the payment intent request generation was successful. It is a boolean value where true denotes success, and false indicates failure.
status string

Describes the status of the payment intent generation request. It is a string providing additional information about the status.
data object | null

Upon success, this property contains detailed information about the payment intent request and related details. If the operation is not successful, the value is null.
errors array

Holds error information if applicable. It is an array containing error details in case there are issues with the payment intent request generation.

object: `data`

terminalPaymentSecretId string

Secret identifier for the payment transaction.
publicKey string

Public key for the payment gateway integration.
languageLCIDCode string

Language code for localization (e.g., "fr-FR").
paymentGateway string

Selected payment gateway (e.g., "STRIPE").
transactInfo object

Details about the transaction (refer to Transaction Details section).

Transaction Details

Comprehensive information about the un-paid invoice transaction of the logged-in user (i.e., Tenant).

object: `data.transactInfo`

transactId string

Transaction ID associated with the booking.
transactDate string

Date of the transaction.
transactAmount object

Details about the transaction amount, including price and formatted price.
payableAmount object

Details about the payable amount, including price and formatted price.
businessInfo object

Business details (refer to Business Details section).
clientInfo object

Client details (refer to Client Details section).
propertyInfo object

Property details (refer to Property Details section).

Client Details

Details about the tenant or client, providing comprehensive information about their identity and contact details.

object: `data.transactInfo.clientInfo`

id unique-identifier

Tenant ID.
name string

Full name of the tenant.
email string

Email address of the tenant.
phoneNumber string

Phone number of the tenant.
address string

Street address of the tenant.
city string

City of residence for the tenant.
region integer

State or Province or County ID (if applicable) for the tenant.
postalCode string

Postal code of the tenant's location.
country object

Details about the client's country, including ID and Name.

Property Details

Details about the property, including property name, address, city, latitude, longitude, postal code, country, and contact number.

object: `data.transactInfo.propertyInfo`

id unique-identifier

Unique identifier for the property.
name string

Name of the property.
address string

Street address of the property.
city string

City where the property is located.
latitude float

Latitude coordinate of the property location.
longitude float

Longitude coordinate of the property location.
postalCode string

Postal code of the property location.
country object

Country where the property is located.
countryISOCode2 string

ISO code (2 characters) for the country of the property.
googlePlaceId string

Google Place ID associated with the property location.
contactNumber string

Contact number for the property.
propertyImageList null or array

List of property images or null if not available.
propertyOfficeOpeningHoursInfoList null or array

List of information about property office opening hours or null if not available (refer to the Property Working Hours section for details).

Property Working Hours

Information about the working hours of the property, including opening and closing times for each day of the week.

array `data.transactInfo.propertyInfo.propertyOfficeOpeningHoursInfoList`

dayOfWeek integer

Day of the week represented as an integer (0 for Sunday, 1 for Monday, ..., 6 for Saturday). The value -1 represents public holidays.
week string

Name of the day of the week in French.
firstTimeSlot string

Opening and closing time of the first time slot, if applicable.
secondTimeSlot string

Opening and closing time of the second time slot, if applicable.
isClosed boolean

Indicates whether the property is closed on the specified day.

Request Header

Authorization: X-API-Key --api-key--
Authorization: X-Token --user-session-token--

API Response

{
    "data": {
        "invoiceId": "f3c0306b-54de-4931-838e-9a9471aa88e2",
        "referenceEntityId": "a19c4789-2e4a-49d7-983a-e5fa707299ff",
        "referenceEntityTransactId": "CSC47",
        "terminalPaymentSecretId": "pi_xxxx",
        "publicKey": "pk_xxx",
        "languageLCIDCode": "fr-FR",
        "paymentGateway": "STRIPE",
        "transactInfo": {
            "transactId": "CIN54",
            "transactDate": "05-02-2024",
            "transactAmount": {
                "price": 106.66,
                "formattedPrice": "106,66 €"
            },
            "payableAmount": {
                "price": 106.66,
                "formattedPrice": "106,66 €"
            },
            "businessInfo": {
                "id": "50a54e81-5cef-4d22-81dd-fe6c6dc851c8",
                "name": "StoRegister"
            },
            "clientInfo": {
                "id": "88da40ab-3183-4f43-b367-583e542719e6",
                "name": "Idette Marion",
                "email": "[email protected]",
                "phoneNumber": "0 345456565",
                "address": "212 avenue des États-Unis",
                "city": "Toulouse",
                "region": 0,
                "postalCode": "31200",
                "country": {
                "id": 82,
                "name": "France"
                }
            },
            "propertyInfo": {
                "id": "a99c4590-9475-404e-bcbd-6cba2e2b5e16",
                "name": "Chalets",
                "address": null,
                "city": "Toulouse",
                "region": {
                    "id": 216,
                    "name": "Occitania"
                },
                "latitude": 0,
                "longitude": 0,
                "postalCode": null,
                "country": {
                    "id": 82,
                    "name": "France"
                },
                "countryISOCode2": null,
                "googlePlaceId": null,
                "contactNumber": null,
                "propertyImageList": null,
                "propertyOfficeOpeningHoursInfoList": null
            },
        }
    },
    "succeeded": true,
    "status": "SUCCESS",
    "errors": null
}

Error Codes

INVALID_PARAM_INVOICE_INFO_ID

INVALID_PARAM_INVOICE_INFO_ID refers to invalid invoice info id.
INVALID_PARAM_PAYMENT_GATEWAY_INFO_ID

INVALID_PARAM_PAYMENT_GATEWAY_INFO_ID refers to invalid payment gateway id or property did not have the payment gateway configuration.
INVALID_PARAM_INVOICE_DETAILS

INVALID_PARAM_INVOICE_DETAILS refers to invalid details.
INVOICE_ALREADY_PAID

INVOICE_ALREADY_PAID refers to invoice already paid, unable to generate payment intent.
INVALID_CLIENT_INFO_DETAILS

INVALID_CLIENT_INFO_DETAILS refers to invalid client info details.
PAYMENT_INTENT_CREATION_FAILED

PAYMENT_INTENT_CREATION_FAILED refers to unable to create payment intent for configured payment gateway.
NO_RECORDS_FOUND

NO_RECORDS_FOUND means there is no relevant information found.
FAILED

FAILED refers to an unsuccessful API call.
SOMETHING_WENT_WRONG

SOMETHING_WENT_WRONG refers to technical glitch. Please contact administrator.

API Reference documentation

Unpaid Invoice Payment Intent Request Generation API