Tribe Payments
Payment Gateway - Hosted Payments API (HPP)

Tribe Payments Gateway Hosted Payments Page API (v3) that lets merchants collect card payments through a Tribe-hosted checkout, offloading PCI scope, plus a webhook interface for asynchronous transaction status notifications. Specification harvested verbatim from the Tribe developer portal.
Documentation GitHub OpenAPI
Documentation

📖
Documentation
https://doc.tribepayments.com/docs/trb-gateway--hosted-payments-api--v3
📖
APIReference
https://doc.tribepayments.com/docs/trb-gateway--hosted-payments-api--v3
Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/tribe-payments/refs/heads/main/openapi/tribe-payments-trb-hpp-api-merchant-api-hpp-v3.json
⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/tribe-payments/refs/heads/main/openapi/tribe-payments-trb-hpp-api-merchant-api-hpp-webhook-v3.json
OpenAPI Specification

{
    "openapi": "3.0.0",
    "info": {
        "title": "Merchant API HPP",
        "version": "3.0.0"
    },
    "servers": [
        {
            "url": "http://127.0.0.1:10010/v3"
        }
    ],
    "paths": {
        "/prepare": {
            "post": {
                "tags": [
                    "Prepare"
                ],
                "summary": "",
                "operationId": "postprepare",
                "requestBody": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Prepare"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/responseSuccess"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/responseError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/responseUnauthorized"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/responseForbidden"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Prepare": {
                "title": "prepare",
                "properties": {
                    "transaction": {
                        "$ref": "#/components/schemas/PrepareTransaction"
                    },
                    "customer": {
                        "$ref": "#/components/schemas/PrepareCustomer"
                    },
                    "settings": {
                        "$ref": "#/components/schemas/PrepareSettings"
                    },
                    "recurring": {
                        "$ref": "#/components/schemas/PrepareRecurring"
                    }
                },
                "type": "object"
            },
            "PrepareTransaction": {
                "type": "object",
                "properties": {
                    "amount": {
                        "description": "Number in minor units, e.g., cents. The value cannot be zero.",
                        "type": "string",
                        "example": "123",
                        "maxLength": 13,
                        "minLength": 1
                    },
                    "currencyCode": {
                        "description": "Currency ISO 4217 code",
                        "type": "string",
                        "example": "EUR",
                        "maxLength": 3,
                        "minLength": 3
                    },
                    "orderId": {
                        "description": "Custom merchant’s reference",
                        "type": "string",
                        "example": "32131231231241",
                        "maxLength": 32,
                        "minLength": 1
                    },
                    "returnUrl": {
                        "description": "After initiating a payment, customer will be redirected to this URL with the transaction result",
                        "type": "string",
                        "example": "https://my-return-server/some-path",
                        "maxLength": 255,
                        "minLength": 1
                    }
                },
                "required": [
                    "amount",
                    "currencyCode",
                    "orderId",
                    "returnUrl"
                ]
            },
            "PrepareCustomer": {
                "type": "object",
                "properties": {
                    "id": {
                        "description": "Unique identifier of the customer in the merchant’s system. Used for applying limits to the customer",
                        "type": "string",
                        "example": "user123",
                        "maxLength": 50,
                        "minLength": 1
                    },
                    "phone": {
                        "description": "Customer’s phone number. Only numbers and, optionally, `+` symbol can be used. Mandatory for all integrations if customer email is not provided.",
                        "type": "string",
                        "example": "0123456789",
                        "maxLength": 20,
                        "minLength": 3
                    },
                    "email": {
                        "description": "Customer’s email address (Mandatory if `send` is `true` in `PrepareSettingsCustomerEmailNotification`). Mandatory for all integrations if customer phone is not provided.",
                        "type": "string",
                        "example": "email@email.com",
                        "maxLength": 50,
                        "minLength": 6
                    },
                    "dateOfBirth": {
                        "description": "Customer’s date of birth. ISO 8601 format: `YYYY-MM-DD`. Required by some providers or when MCC is 6012",
                        "type": "string",
                        "example": "2000-01-01",
                        "maxLength": 10,
                        "minLength": 10
                    },
                    "countryCode": {
                        "description": "Customer’s billing country. [`Country list`](#appendix--enum--country)",
                        "type": "string",
                        "example": "GB",
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "state": {
                        "description": "State or province of the customer’s billing address, as defined in ISO 3166-2, e.g. US Alabama: AL",
                        "type": "string",
                        "example": "AL",
                        "maxLength": 3,
                        "minLength": 1
                    },
                    "city": {
                        "description": "Customer’s billing city. Required by some integrations with 3DS v2 and if avs_check is `true`",
                        "type": "string",
                        "example": "City",
                        "maxLength": 85,
                        "minLength": 1
                    },
                    "address": {
                        "description": "Customer’s billing address. Required by some integrations with 3DS v2 and if avs_check is `true`",
                        "type": "string",
                        "example": "Address",
                        "maxLength": 100,
                        "minLength": 1
                    },
                    "zipCode": {
                        "description": "Customer’s billing ZIP code. Required by some integrations with 3DS v2. Required if avs_check is `true`",
                        "type": "string",
                        "example": "GU16 7HF",
                        "maxLength": 20,
                        "minLength": 1
                    },
                    "ip": {
                        "description": "IPv4 or IPv6 address. Required by some integrations.",
                        "type": "string",
                        "example": "1.1.1.1",
                        "maxLength": 40,
                        "minLength": 7
                    },
                    "firstName": {
                        "description": "Customer’s first name",
                        "type": "string",
                        "example": "John",
                        "maxLength": 255,
                        "minLength": 1
                    },
                    "lastName": {
                        "description": "Customer’s last name",
                        "type": "string",
                        "example": "Doe",
                        "maxLength": 255,
                        "minLength": 1
                    }
                }
            },
            "PrepareSettings": {
                "type": "object",
                "properties": {
                    "allowedNumberOfRetries": {
                        "description": "Max number of customer attempts to finish the payment before redirecting to Merchant returnUrl",
                        "type": "integer",
                        "example": 3
                    },
                    "expiresInHours": {
                        "description": "Expiration in hours (if not provided - default value from hosted payment setting will be used)",
                        "type": "integer",
                        "example": 2
                    },
                    "hppSettingId": {
                        "description": "Hosted Payment Setting ID (if not provided - default company or default brand Hosted Payment Setting will be selected)",
                        "type": "integer",
                        "example": 1
                    },
                    "paymentMethod": {
                        "description": "This parameter only accepts the value `cc`(Credit Card) (Sale transactions will be processed via the link generated using this payment method).",
                        "type": "string",
                        "example": "cc",
                        "maxLength": 50,
                        "minLength": 1
                    },
                    "checkoutMethods": {
                        "description": "Possible checkout methods will be received from Gateway",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "example": "cc"
                        }
                    },
                    "paymentDescription": {
                        "description": "Provided payment description will be displayed in the Hosted Payment page",
                        "type": "string",
                        "example": "Some text",
                        "maxLength": 100,
                        "minLength": 1
                    },
                    "termsAndReferencesUrl": {
                        "description": "Terms and References URL",
                        "type": "string",
                        "example": "https://www.example.com/terms-and-references.html",
                        "maxLength": 200,
                        "minLength": 1
                    },
                    "hideAmount": {
                        "description": "Possible values: `true` or `false`. If the value is set to `true`, the Amount will be hidden.",
                        "type": "boolean",
                        "example": true
                    },
                    "hideOrderId": {
                        "description": "Possible values: `true` or `false`. If the value is set to `true`, the Order ID will be hidden.",
                        "type": "boolean",
                        "example": true
                    },
                    "slimMode": {
                        "description": "Possible values: `true` or `false`. If the value is set to `true`, Slim Mode will be enabled.",
                        "type": "boolean",
                        "example": true
                    },
                    "customerEmailNotification": {
                        "$ref": "#/components/schemas/PrepareSettingsCustomerEmailNotification"
                    }
                },
                "required": [
                    "paymentMethod"
                ]
            },
            "PrepareRecurring": {
                "type": "object",
                "properties": {
                    "paymentType": {
                        "description": "Recurring payment type. Possible values: `1` - scheduled recurring payment; `2` - unscheduled MIT payment",
                        "type": "integer",
                        "example": 1
                    },
                    "frequency": {
                        "description": "[`Recurring frequency`](#appendix--enum--recurring-frequency). Mandatory if paymentType=1",
                        "type": "integer",
                        "example": 1
                    },
                    "endDate": {
                        "description": "Recurring end date. Format: `YYYYMMDD`. Mandatory if paymentType=1",
                        "type": "string",
                        "example": "20230901",
                        "maxLength": 8,
                        "minLength": 8
                    }
                }
            },
            "PrepareSettingsCustomerEmailNotification": {
                "type": "object",
                "properties": {
                    "send": {
                        "description": "Possible values: `true` or `false`. If the value is set to `true`, the `customer.email` field is mandatory.",
                        "type": "boolean",
                        "example": true
                    },
                    "subjectTag": {
                        "description": "Additional email subject tag which can be added in email template ([payment_link_prepare_email_subject]).",
                        "type": "string",
                        "example": "#Order XYZ-987",
                        "maxLength": 255,
                        "minLength": 1
                    },
                    "messageTag": {
                        "description": "Additional email message tag which can be added in email template ([payment_link_prepare_email_message]",
                        "type": "string",
                        "example": "Dear John Doe, Your #Order XYZ-987 was completed with greatest success.",
                        "maxLength": 255,
                        "minLength": 1
                    }
                }
            },
            "responseSuccess": {
                "title": "Success response",
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    }
                },
                "type": "object"
            },
            "responseError": {
                "title": "Error response",
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    },
                    "message": {
                        "description": "Error response",
                        "type": "string",
                        "example": "Error occurred"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/violationObject"
                        },
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "responseErrorReport": {
                "title": "Error response",
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    },
                    "message": {
                        "description": "Error response",
                        "type": "string",
                        "example": "Error occurred"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/violationObjectReport"
                        },
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "responseErrorDisputes": {
                "title": "Error response",
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    },
                    "message": {
                        "description": "Error response",
                        "type": "string",
                        "example": "Error occurred"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/violationObjectDisputes"
                        },
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "responseErrorProcessing": {
                "title": "Error response",
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    },
                    "message": {
                        "description": "Error response",
                        "type": "string",
                        "example": "Error occurred"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/violationObjectProcessing"
                        },
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "responseErrorTransactions": {
                "title": "Error response",
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    },
                    "message": {
                        "description": "Error response",
                        "type": "string",
                        "example": "Error occurred"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/violationObjectTransactions"
                        },
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "responseUnauthorized": {
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    },
                    "message": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "Unauthorized request"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [],
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "responseForbidden": {
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    },
                    "message": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "Error occurred"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/violationObjectForbidden"
                        }
                    }
                },
                "type": "object"
            },
            "responseTooManyRequests": {
                "properties": {
                    "requestId": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "b44724c9-3844-450d-b36a-986fc9c38d7b",
                        "maxLength": 36,
                        "minLength": 36
                    },
                    "message": {
                        "description": "Request ID",
                        "type": "string",
                        "example": "Too many requests"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/violationObjectTooManyRequests"
                        }
                    }
                },
                "type": "object"
            },
            "violationObjectProcessing": {
                "title": "Validation object disputes",
                "properties": {
                    "code": {
                        "description": "[`Response code`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 5,
                        "minLength": 3,
                        "example": "1004"
                    },
                    "message": {
                        "description": "[`Response message`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 50,
                        "minLength": 1,
                        "example": "Request body contains unknown field \\\"parameterName\\\""
                    }
                },
                "type": "object"
            },
            "violationObjectTransactions": {
                "title": "Validation object disputes",
                "properties": {
                    "code": {
                        "description": "[`Response code`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 5,
                        "minLength": 3,
                        "example": "1005"
                    },
                    "message": {
                        "description": "[`Response message`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 50,
                        "minLength": 1,
                        "example": "Request body must not be empty"
                    }
                },
                "type": "object"
            },
            "violationObjectDisputes": {
                "title": "Validation object disputes",
                "properties": {
                    "propertyPath": {
                        "description": "Path of parameter causing an error. Null for general errors",
                        "type": "string",
                        "example": "parameterName",
                        "maxLength": 50,
                        "minLength": 1,
                        "nullable": true
                    },
                    "code": {
                        "description": "[`Response code`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 5,
                        "minLength": 3,
                        "example": "3007"
                    },
                    "message": {
                        "description": "[`Response message`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 50,
                        "minLength": 1,
                        "example": "Invalid date format"
                    }
                },
                "type": "object"
            },
            "violationObjectReport": {
                "title": "Validation object disputes",
                "properties": {
                    "code": {
                        "description": "[`Response code`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 5,
                        "minLength": 3,
                        "example": "1004"
                    },
                    "message": {
                        "description": "[`Response message`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 50,
                        "minLength": 1,
                        "example": "Request body contains unknown field \"randomName\""
                    }
                },
                "type": "object"
            },
            "violationObjectForbidden": {
                "title": "Validation object",
                "properties": {
                    "code": {
                        "description": "[`Response code`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 5,
                        "minLength": 3,
                        "example": "4001"
                    },
                    "message": {
                        "description": "[`Response message`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 50,
                        "minLength": 1,
                        "example": "Company is disabled"
                    }
                },
                "type": "object"
            },
            "unprocessableContent": {
                "title": "Validation object",
                "properties": {
                    "code": {
                        "description": "[`Response code`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 5,
                        "minLength": 3,
                        "example": "4005"
                    },
                    "message": {
                        "description": "[`Response message`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 50,
                        "minLength": 1,
                        "example": "Company webhook URL is not set"
                    }
                },
                "type": "object"
            },
            "violationObjectTooManyRequests": {
                "title": "Validation object",
                "properties": {
                    "code": {
                        "description": "[`Response code`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 5,
                        "minLength": 3,
                        "example": "4004"
                    },
                    "message": {
                        "description": "[`Response message`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 50,
                        "minLength": 1,
                        "example": "Retry after 30 seconds"
                    }
                },
                "type": "object"
            },
            "violationObject": {
                "title": "Validation object",
                "properties": {
                    "propertyPath": {
                        "description": "Path of parameter causing an error. Null for general errors",
                        "type": "string",
                        "example": "parameterName",
                        "maxLength": 50,
                        "minLength": 1,
                        "nullable": true
                    },
                    "code": {
                        "description": "[`Response code`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 5,
                        "minLength": 3,
                        "example": "2000"
                    },
                    "message": {
                        "description": "[`Response message`](#appendix--enum--response-code)",
                        "type": "string",
                        "maxLength": 50,
                        "minLength": 1,
                        "example": "Value is not provided"
                    }
                },
                "type": "object"
            }
        },
        "securitySchemes": {
            "accountId": {
                "type": "apiKey",
                "in": "header",
                "name": "x-auth-account-id"
            },
            "accountPassword": {
                "type": "apiKey",
                "in": "header",
                "name": "x-auth-account-password"
            }
        }
    },
    "security": [
        {
            "accountId": [],
            "accountPassword": []
        }
    ]
}