--- title: "Troy Debit" canonical_url: https://docs.connect.worldline-solutions.com/payment-product/troy-debit/integration/globalcollect --- * [Overview](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/overview.md) * [Countries \& currencies](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/countries-and-currencies.md) * [Integration](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/integration.md) * [Process flows](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/process-flows.md) * [Testing](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/testing.md) * [Additional information](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/additional-information.md) * [Consumer experience](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/consumer-experience.md) * [FAQ](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/faqs.md) # Integration * [Using MyCheckout hosted payment pages](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/integration/globalcollect.md#mycheckout) * [Using your own checkout page](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/integration/globalcollect.md#own-checkout) * [Client-side encryption](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/integration/globalcollect.md#client-side-encryption) * [Raw data](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/integration/globalcollect.md#raw-data) * [Delayed capture](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/integration/globalcollect.md#delayed) * [Refunds and cancellations](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/integration/globalcollect.md#refunds) ## Before you begin To follow along with this guide, please ensure that you have the following ready: * The correct [API endpoint](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/endpoints.html?paymentPlatform=ALL) * A way to construct the [authorization header](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/authentication.html?paymentPlatform=ALL) (API Explorer, [SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/.md), etc.) * A way to send REST API calls (API Explorer, [SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/.md), etc.) ## Using MyCheckout hosted payment pages 1. Make a [POST /v1/{merchantId}/hostedcheckouts](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/create.html?paymentPlatform=ALL) API call. 2. Create the order object containing the following elements: * amountOfMoney, including amount and currencyCode * customer, including merchantCustomerId, billingAddress, and countryCode * hostedCheckoutSpecificInput, including the checkout page variant you designed and locale POST HOSTEDCHECKOUTS REQUESTCopy { "order": { "amountOfMoney": { "amount": 100, "currencyCode": "TRY" }, "customer": { "merchantCustomerId": "1234567", "billingAddress": { "countryCode": "TR" } } }, "hostedCheckoutSpecificInput": { "variant": "124", "locale": "tur_TR" } } POST HOSTEDCHECKOUTS RESPONSECopy { "RETURNMAC" : "ed471a7d-4126-45c9-ba08-89c1bde5bcd6", "hostedCheckoutId" : "0651ea55-a68e-71ff-a30d-e274bfca236a", "partialRedirectUrl" : "pay2.preprod.checkout.worldline-solutions.com/checkout/9991-faa4d336e2384de3bde7ce62beb3f127:065e9dd7-b56e-71ff-8ded-48133a47970b:2dc35d06fa7a43c19b22cca466a50cdd" } From the response, the important properties are: * hostedCheckoutId -- can be used in subsequent API calls to retrieve the transaction details, such as [GET/v1/{merchantId}/hostedcheckouts/{hostedCheckoutId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/get.html?paymentPlatform=ALL) * partialRedirectUrl -- is used to create the URL to which the customer needs to be redirected (by default, we configure every account with the subdomain payment, so you can always connect **https://payment.** with the partialRedirectUrl, for example: https://payment.pay2.preprod.checkout.worldline-solutions.com/checkout/9991-faa4d336e2384de3bde7ce62beb3f127:065e9dd7-b56e-71ff-8ded-48133a47970b:2dc35d06fa7a43c19b22cca466a50cdd The hostedCheckoutId is only valid for 2 hours, please ensure to store the createdPaymentOutput.payment.id from the [GET /v1/{merchantId}/hostedcheckouts/{hostedCheckoutId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/get.html?paymentPlatform=ALL) response to be able to retrieve data after 2 hours have elapsed via the [GET /v1/{merchantId}/payments/{paymentId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/get.html?paymentPlatform=ALL) API call. Alternatively, we can also optionally send a [webhook event](https://docs.connect.worldline-solutions.com/documentation/webhooks/index.md) that will contain it. ## Using your own checkout page You can build a direct integration using our [SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/index.md) (or integrate our API from scratch). Depending on your integration needs, there are several options available. ### Client-side encryption Our [Client API](https://apireference.connect.worldline-solutions.com/c2sapi/v1/en_US/index.html?paymentPlatform=ALL) allows you to perform various actions, such as collecting card data without being PCI SAQ-D compliant. All you need is to be able to create a session via the [POST /v1/{merchantId}/sessions](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/sessions/create.html?paymentPlatform=ALL) API call, which will grant you access to the Client API. It's highly recommended that you use our [Client SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/.md), provided for the following programming languages: * [JavaScript](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/javascript/.md) * [Java](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/android/.md) * [Swift](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/swift/.md) * [Objective-C](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/ios/.md) We also have reference implementations showing how to use these SDKs on [GitHub](https://github.com/worldline-global-collect). If you choose not to use our Client SDKs, please use the encryption methods we provide in these SDKs, as it can be a bit tricky to do a custom implementation. ### Raw data If you wish to do a direct server-to-server API call, go for this option. The difference with the other options mentioned before is that you don't need to submit an encryptedCustomerInput property. After the customer selects the payment product, you need to perform the following: 1. Make a [POST /v1/{merchantId}/payments](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/create.html?paymentPlatform=ALL) API call. 2. Create the order object requiring the following properties: * amountOfMoney, including amount and currencyCode * customer, including billingAddress and countryCode 1. Create the cardPaymentMethodSpecificInput object requiring the following properties: * paymentProductId * card, including cardNumber, expiryDate, cvv, and cardholderName The cardholderName is often different from the name a customer uses when registering an account. The cardholderName refers to the official name the customer uses with their issuing bank. POST PAYMENTS REQUESTCopy { "order": { "amountOfMoney": { "amount": 100, "currencyCode": "TRY" }, "customer": { "merchantCustomerId": "1234567", "billingAddress": { "countryCode": "TR" } } }, "cardPaymentMethodSpecificInput": { "paymentProductId": 189, "card": { "cvv": "000", "cardNumber": "9792052565200015", "expiryDate": "0127", "cardholderName": "Cevdet Deger" } } } POST PAYMENTS RESPONSECopy { "creationOutput" : { "additionalReference" : "00000997021000000883", "externalReference" : "000009970210000008830000100001" }, "payment" : { "id" : "000009970210000008830000100001", "paymentOutput" : { "amountOfMoney" : { "amount" : 100, "currencyCode" : "TRY" }, "references" : { "paymentReference" : "0", "providerId" : "4700", "providerReference" : "200198342" }, "paymentMethod" : "card", "cardPaymentMethodSpecificOutput" : { "paymentProductId" : 189, "authorisationCode" : "P05419", "fraudResults" : { "fraudServiceResult" : "no-advice", "avsResult" : "0", "cvvResult" : "0" }, "card" : { "cardNumber" : "************0015", "cardholderName" : "Cevdet Deger", "expiryDate" : " 0127" } } }, "status" : "CAPTURE_REQUESTED", "statusOutput" : { "isCancellable" : false, "isRetriable" : false, "statusCategory" : "PENDING_CONNECT_OR_3RD_PARTY", "statusCode" : 975, "statusCodeChangeDateTime" : "20231006005621", "isAuthorized" : true, "isRefundable" : true } } } ## Delayed capture Changing the authorization type modifies the behavior for both the customer and you as a merchant. From the customer's point of view, the key factor that differs is how long the authorization stays valid. This duration may vary slightly depending on the specific payment scheme and industry: * **Pre-authorizations** are valid for ±30 days: you may capture an amount lower than authorized, and you can perform the capture at any time during the authorization period. * **Final authorizations** are valid for ±7 days: you must capture the exact amount authorized, and you can perform the capture at any time during the authorization period. * **Sale authorizations** are captured immediately The values are PRE_AUTHORIZATION, FINAL_AUTHORIZATION, or SALE. The optional property authorizationMode in the cardPaymentMethodSpecificInput object can be used to set the type of authorization you're sending. It applies to both API calls: * [POST /v1/{merchantId}/hostedcheckouts](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/create.html?paymentPlatform=ALL) * [POST /v1/{merchantId}/payments](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/create.html?paymentPlatform=ALL) Final authorization and pre-authorization (either through the API or via configuration) allow you to choose when to perform a capture. However, to do that, you must submit the requiresApproval property. Just like the authorization type, you can also contact us to make this a fixed setting, so you don't need to send the requiresApproval in the request every time. Here's an example of setting the property for the [POST /v1/{merchantId}/payments](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/create.html?paymentPlatform=ALL) API call: POST PAYMENTS REQUESTCopy { "order": { "amountOfMoney": { "amount": 100, "currencyCode": "TRY" }, "customer": { "merchantCustomerId": "1234567", "billingAddress": { "countryCode": "TR" } } }, "cardPaymentMethodSpecificInput": { "paymentProductId": 189, "card": { "cvv": "000", "cardNumber": "9792052565200015", "expiryDate": "0127", "cardholderName": "Cevdet Deger" }, "requiresApproval": true, "authorizationMode": "PRE_AUTHORIZATION" } } Contact us to make this setting permanent so that you don't need to send authorization type and requiresApproval in the request. If you don't set requiresApproval, regardless of which authorization type you use, it will behave as the **Sale authorization**. After the customer finished the payment, [GET /v1/{merchantId}/payments/{paymentId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/get.html?paymentPlatform=ALL) will return a response: **Expand example code** GET PAYMENTS RESPONSECopy { "createdPaymentOutput" : { "payment" : { "id" : "000009970210000008930000100001", "hostedCheckoutSpecificOutput" : { "hostedCheckoutId" : "0651fe3b-9d34-71ff-8643-1f65afc02123", "variant" : "124" }, "paymentOutput" : { "amountOfMoney" : { "amount" : 100, "currencyCode" : "TRY" }, "references" : { "paymentReference" : "0", "providerId" : "4700", "providerReference" : "200198375" }, "paymentMethod" : "card", "cardPaymentMethodSpecificOutput" : { "paymentProductId" : 189, "authorisationCode" : "P02478", "fraudResults" : { "fraudServiceResult" : "no-advice", "avsResult" : "0", "cvvResult" : "0" }, "card" : { "cardNumber" : "************0015", "cardholderName" : "Cevdet Deger", "expiryDate" : "0127" } } }, "status" : "PENDING_APPROVAL", "statusOutput" : { "isCancellable" : true, "isRetriable" : false, "statusCategory" : "PENDING_MERCHANT", "statusCode" : 680, "statusCodeChangeDateTime" : "20231006123902", "isAuthorized" : true, "isRefundable" : false } }, "paymentCreationReferences" : { "additionalReference" : "00000997021000000893", "externalReference" : "000009970210000008930000100001" }, "paymentStatusCategory" : "SUCCESSFUL" }, "status" : "PAYMENT_CREATED" } As seen above, the status will be changed to PENDING_APPROVAL (and not CAPTURE_REQUESTED, which is the usual status of a successful payment), indicating that it requires your approval to continue. You need to send the approval with the [POST /v1/{merchantId}/payments/{paymentId}/approve](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/approve.html?paymentPlatform=ALL) API call to let us perform the capture. You may capture any amount equal to or lower than the authorized amount. After we receive your approval to capture, we'll proceed with the transaction, and the status will change to CAPTURE_REQUESTED. Once the request is processed, [POST /v1/{merchantId}/payments/{paymentId}/approve](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/approve.html?paymentPlatform=ALL) will return a response: **Expand request example** POST APPROVE REQUESTCopy { "payment" : { "id" : "000009970210000008900000100001", "paymentOutput" : { "amountOfMoney" : { "amount" : 100, "currencyCode" : "TRY" }, "references" : { "paymentReference" : "0", "providerId" : "4700", "providerReference" : "200198351" }, "paymentMethod" : "card", "cardPaymentMethodSpecificOutput" : { "paymentProductId" : 189, "authorisationCode" : "P44066", "fraudResults" : { "fraudServiceResult" : "no-advice", "avsResult" : "0", "cvvResult" : "0" }, "card" : { "cardNumber" : "************0015", "cardholderName" : "Cevdet Deger", "expiryDate" : "0127" } } }, "status" : "CAPTURE_REQUESTED", "statusOutput" : { "isCancellable" : true, "isRetriable" : false, "statusCategory" : "PENDING_CONNECT_OR_3RD_PARTY", "statusCode" : 800, "statusCodeChangeDateTime" : "20231006123230", "isAuthorized" : true, "isRefundable" : false } } } After the capture is processed, [GET /v1/{merchantId}/payments/{paymentId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/get.html?paymentPlatform=ALL) will return a response: **Expand response example** GET PAYMENTS RESPONSECopy { "id" : "000009970210000008900000100001", "paymentOutput" : { "amountOfMoney" : { "amount" : 100, "currencyCode" : "TRY" }, "references" : { "paymentReference" : "0", "providerId" : "4700", "providerReference" : "200198351" }, "paymentMethod" : "card", "cardPaymentMethodSpecificOutput" : { "paymentProductId" : 189, "authorisationCode" : "P44066", "fraudResults" : { "fraudServiceResult" : "no-advice", "avsResult" : "0", "cvvResult" : "0" }, "card" : { "cardNumber" : "************0015", "cardholderName" : "Cevdet Deger", "expiryDate" : "0127" } } }, "status" : "CAPTURE_REQUESTED", "statusOutput" : { "isCancellable" : true, "isRetriable" : false, "statusCategory" : "PENDING_CONNECT_OR_3RD_PARTY", "statusCode" : 800, "statusCodeChangeDateTime" : "20231006123230", "isAuthorized" : true, "isRefundable" : false } } ## Refunds and cancellations If you wish to cancel a payment, you have two opportunities to do so: before the capture and after the capture. Depending on the situation, you need to send a separate API call. | | API call | Conditions | |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Before capture | [POST/v1/{merchantId}/payments/{paymentId}/cancel](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/cancel.html?paymentPlatform=ALL) | Only when the status is PENDING_APPROVAL and statusOutput.isCancellable is **true** | | After capture | [POST /v1/{merchantId}/payments/{paymentId}/refund](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/refund.html?paymentPlatform=ALL) | Only when the status is CAPTURED. You can refund any amount equal or lower than the captured amount, and may do this until the total captured amount has been refunded. | A basic refund payload only requires the amountOfMoney object specifying the amount and currencyCode: Copy text { "amountOfMoney": { "currencyCode": "TRY", "amount": 100 } } If you'd like to see the details of your refund, use the [GET /v1/{merchantId}/refunds/{refundId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/refunds/get.html?paymentPlatform=ALL) API call: GET REFUNDS REQUESTCopy { "id" : "00000997021000000896000-100001", "refundOutput" : { "amountOfMoney" : { "amount" : 100, "currencyCode" : "TRY" }, "references" : { "paymentReference" : "0" }, "paymentMethod" : "card", "cardRefundMethodSpecificOutput" : { "refundProductId" : 189 } }, "status" : "PENDING_APPROVAL", "statusOutput" : { "isCancellable" : true, "statusCategory" : "PENDING_MERCHANT", "statusCode" : 600, "statusCodeChangeDateTime" : "20231009213433" } } [Next Process flows](https://docs.connect.worldline-solutions.com/payment-product/troy-debit/process-flows.md)