diff --git a/connector-api/SUMMARY.md b/connector-api/SUMMARY.md index 5d3fc480..0f2c73ea 100644 --- a/connector-api/SUMMARY.md +++ b/connector-api/SUMMARY.md @@ -79,6 +79,7 @@ * [Outlet items](operations/outletitems.md) * [Outlets](operations/outlets.md) * [Payments](operations/payments.md) + * [Payment method requests](operations/paymentmethodrequests.md) * [Payment plans](operations/paymentplans.md) * [Payment requests](operations/paymentrequests.md) * [Preauthorizations](operations/preauthorizations.md) diff --git a/connector-api/_generator/types.yaml b/connector-api/_generator/types.yaml index f26894a4..525e693e 100644 --- a/connector-api/_generator/types.yaml +++ b/connector-api/_generator/types.yaml @@ -2604,3 +2604,15 @@ types: billtypeenum: file: bills.md anchor: bill-type + paymentmethodrequestadditionresult: + file: paymentmethodrequests.md + anchor: payment-method-request-addition-result + paymentmethodrequestaddparameters: + file: paymentmethodrequests.md + anchor: payment-method-request-parameters + paymentmethodrequestpaymentmethodsenum: + file: paymentmethodrequests.md + anchor: acceptable-payment-methods + paymentmethodrequestemailtypesenum: + file: paymentmethodrequests.md + anchor: supported-email-types diff --git a/connector-api/changelog/README.md b/connector-api/changelog/README.md index 2524828e..5d3a8a67 100644 --- a/connector-api/changelog/README.md +++ b/connector-api/changelog/README.md @@ -7,6 +7,8 @@ - [Get service availability (ver 2024-01-22)](../operations/services.md#get-service-availability-ver-2024-01-22): - Extended [Service availability metrics](../operations/services.md#service-availability-metrics) with `HouseUse`. +- [Add payment method request](../operations/paymentmethodrequests.md#add-payment-method-request): + - New operation. Adds a payment method request to a customer or company account, prompting them to provide a payment method such as a payment card or SEPA direct debit. {% endupdate %} {% update date="2026-02-10" %} diff --git a/connector-api/operations/README.md b/connector-api/operations/README.md index 37eabdb8..24a59b21 100644 --- a/connector-api/operations/README.md +++ b/connector-api/operations/README.md @@ -137,6 +137,7 @@ This section describes all operations supported by the API, organised here by th | [Get all payment requests](paymentrequests.md#get-all-payment-requests) | Returns all payment requests | | [Add payment requests](paymentrequests.md#add-payment-requests) | Adds new payment requests for specified customers | | [Cancel payment requests](paymentrequests.md#cancel-payment-requests) | Cancels specified pending payment requests | +| [Add payment method request](paymentmethodrequests.md#add-payment-method-request) | Adds a payment method request to prompt a customer or company to provide a payment method | | [Add outlet bills](outletbills.md#add-outlet-bills) | Adds new outlet bills with their items | | [Get all order items](orderitems.md#get-all-order-items) | Returns all order items | | [Cancel order items](orderitems.md#cancel-order-items) | **Restricted!** Cancels specified order items | diff --git a/connector-api/operations/paymentmethodrequests.md b/connector-api/operations/paymentmethodrequests.md new file mode 100644 index 00000000..ca3d6a48 --- /dev/null +++ b/connector-api/operations/paymentmethodrequests.md @@ -0,0 +1,69 @@ + +# Payment method requests + +## Add payment method request + +> ### Restricted! +> This operation is currently in beta-test and as such it is subject to change. + +Create a payment method request for the specified customer or company account to securely collect a payment method without charging the guest immediately. An optional email notification is sent to the account's email address or a specified override address. Note this operation supports [Portfolio Access Tokens](../concepts/multi-property.md). + +### Request + +`[PlatformAddress]/api/connector/v1/paymentMethodRequests/add` + +```javascript +{ + "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", + "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", + "Client": "Sample Client 1.0.0", + "AccountId": "fadd5bb6-b428-45d5-94f8-fd0d89fece6d", + "ExpirationUtc": "2024-02-23T23:00:00Z", + "Description": "Please provide a payment card to secure your reservation.", + "Notes": "Sent via Connector API", + "PaymentMethods": [ + "PaymentCard", + "SepaDirectDebit" + ], + "Email": "john.smith@example.com", + "EmailsToSend": [ + "PaymentMethodRequestAdded" + ], + "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" +} +``` + +| Property | Type | Contract | Description | +| :-- | :-- | :-- | :-- | +| `ClientToken` | string | required | Token identifying the client application. | +| `AccessToken` | string | required | Access token of the client application. | +| `Client` | string | required | Name and version of the client application. | +| `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](../concepts/multi-property.md), ignored otherwise. | +| `AccountId` | string | required | Unique identifier of the account (`Customer` or `Company`) to which the payment method request is issued. | +| `ExpirationUtc` | string | required | Date and time of the payment method request's expiration in ISO 8601 format. | +| `Description` | string | required, max length 1000 characters | Description of the payment method request displayed to the customer. | +| `Notes` | string | optional, max length 1000 characters | Payment method request's internal notes. | +| `PaymentMethods` | array of [Acceptable payment methods](paymentmethodrequests.md#acceptable-payment-methods) | required | Collectable payment methods. | +| `Email` | string | optional, max length 500 characters | Account email address for sending the payment method request. If not provided, uses the email from the customer profile. | +| `EmailsToSend` | array of [Supported email types](paymentmethodrequests.md#supported-email-types) | optional | Email notifications to send. If not specified, all emails will be sent. To disable all emails send an empty list. Additional email types may be added in the future. | + +#### Acceptable payment methods + +* `PaymentCard` +* `SepaDirectDebit` + +#### Supported email types + +* `PaymentMethodRequestAdded` + +### Response + +```javascript +{ + "PaymentMethodRequestId": "a5f5c82d-621a-4c8a-903b-1b0a9a23b71e" +} +``` + +| Property | Type | Contract | Description | +| :-- | :-- | :-- | :-- | +| `PaymentMethodRequestId` | string | required | Unique identifier of the created payment method request. |