# BANCOMAT Pay (/bancomat) BANCOMAT Pay is a local payment method that a customer can use to place an order and then complete the payment with their BANCOMAT Pay mobile digital wallet app. | Countries | Payment type | Payment flow | Currencies | Maximum amount | Refunds | | ------------ | ------------ | ------------ | ---------- | -------------- | --------------- | | Italy (`IT`) | wallet | redirect | `EUR` | N/A | Within 365 days | ## How it works [#how-it-works] ![Alternative,payment,methods,diagram](https://www.paypalobjects.com/ppdevdocs/img/docs/apm/unbranded-flow.svg) 1. Your checkout page offers alternative payment methods. 2. Buyer provides their personal details and selects an alternative payment method from your checkout page. 3. Buyer is transferred from your checkout page to the third-party bank to confirm the purchase. 4. Buyer authorizes and confirms payment. 5. Buyer returns to your site to see confirmation of purchase. 6. Merchant initiates completion of payment. PayPal moves the funds to the merchant. Transaction shows in your PayPal account with the payment method the buyer used. ## Eligibility [#eligibility] * Available to merchants globally, except in Russia, Japan, and Brazil. * Billing agreements, multiple seller payments, and shipping callback aren't supported. * Support for order capture only (order authorize is not supported). See authorized and captured payments. * Chargebacks aren't supported. * Transaction must be an online purchase (buy online, pay in store is not supported). ## Know before you code [#know-before-you-code] * The steps to implementing all alternative payment methods using the Orders V2 REST API are similar. If you've implemented an alternative payment method previously, you can likely use that code and adjust it for the specific differences for BANCOMAT Pay. * Make sure you're [subscribed to the following webhook events](/payment-methods/webhooks): * The `PAYMENT.CAPTURE.COMPLETED` webhook event indicates a successful order capture. * The `PAYMENT.CAPTURE.DENIED` webhook event indicates a failed order capture. Upon receiving each webhook, fetch the latest order details using [Show order details](/api/orders/v2/orders-get/). The `up` HATEOAS link in the webhook payload indicates the order associated with the capture. * When processing BANCOMAT Pay payments, capture payment for order is not required. ## 1. Offer BANCOMAT Pay on your checkout page [#1-offer-bancomat-pay-on-your-checkout-page] You'll need to create the user interface to offer BANCOMAT Pay and collect the buyer's full name and phone number. Then you'll use the API calls described in the remainder of this topic to: * Create the order with BANCOMAT Pay as the payment method and the buyer's `full name`, `country_code`, and `phone`. * The buyer receives a notification in the BANCOMAT Pay mobile app to complete the payment. * (Optional) `brand_name` is supported in create order. Refer to [Payment method icons](/beta/apm-beta/additional-information/method-icons/) for icons you can use and download locations. ## 2. Create an order with BANCOMAT Pay as the payment source [#2-create-an-order-with-bancomat-pay-as-the-payment-source] Use the buyer information you captured from your user interface to create an order with BANCOMAT Pay as the payment source. ### Sample request [#sample-request] API endpoint used: [Create order](/api/orders/v2/orders-create/)
```bash lineNumbers curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'PayPal-Request-Id: ' \ --data-raw '{ "intent": "CAPTURE", "payment_source": { "bancomatpay": { "country_code": "IT", "name": "Firstname Lastname", "phone": { "national_number": "1234567890", "country_code": "39" }, "experience_context": { "brand_name": "brand name override" } } }, "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL", "purchase_units": [ { "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b", "amount": { "currency_code": "EUR", "value": "100.00" } } ] }' ``` ### Modify the code [#modify-the-code] After you copy the code in the sample request, modify the following: * `Access-Token` - Your [access token](/api/rest/authentication). * `PayPal-Request-Id` - Replace the sample ID with a unique ID you generate. This ID helps prevent duplicate authorizations in the event that the API call is disrupted. See also: [API idempotency](/reference/guidelines/idempotency/). * `intent` - This parameter must be set to `CAPTURE` as it is in this sample code. * `payment_source` - Specify the following: * `bancomatpay` as the `payment_source` and include the `country_code`. * buyer's full name in the `name` field. * buyer's phone number associated with BANCOMAT Pay in the `national_number` field and country code in the `country_code` field. * `experience_context` - Specify the brand name in the `brand_name` field. * `processing_instruction` - Set this value to `ORDER_COMPLETE_ON_PAYMENT_APPROVAL` as it is in this sample code. * `purchase_units: amount` - Pass the amount of the order and the currency code. * `reference_id` - Provide the ID for the purchase unit. > **Note:** **Note:** Change or add other parameters in the [Create order request body](/api/orders/v2/orders-create/) to create an order that reflects the actual order details. ### Step result [#step-result] A successful request results in the following: * A return status code of HTTP `200 OK`. * A JSON response body that contains the order ID. You'll use the order ID and `payer-action` HATEOAS URL in the next step. See also: [HATEOAS links](/api/rest/responses/#hateoas-links). ### Sample response [#sample-response]
```json lineNumbers { "id": "5V159329PV571861D", "status": "PAYER_ACTION_REQUIRED", "payment_source": { "bancomatpay": { "name": "Firstname Lastname", "country_code": "IT" } }, "links": [ { "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D", "rel": "self", "method": "GET" } ] } ``` ## 3. No redirection of buyer to approve purchase [#3-no-redirection-of-buyer-to-approve-purchase] BANCOMAT Pay sends a push notification directly to the buyer's mobile app. The buyer stays on your website while approving the transaction in the mobile app, and no redirection action is required. After the buyer approves the purchase, the payment is automatically captured. ## 4. Listen to webhooks to get the result of payment status [#4-listen-to-webhooks-to-get-the-result-of-payment-status] Listen to the following webhooks to get the result of order capture: * The `PAYMENT.CAPTURE.COMPLETED` webhook event indicates a successful order capture. * The `PAYMENT.CAPTURE.DENIED` and `CHECKOUT.PAYMENT-APPROVAL.REVERSED` webhook events indicate a failed order capture. * Optional: Use the [Show order details](/api/orders/v2/orders-get/) endpoint to determine the status of an order. * The `up` HATEOAS link indicates the order associated with this capture. See [Subscribe to checkout webhooks](/payment-methods/webhooks) for more information. Here are some additional resources as you create webhook handler code: * [Webhook Management API](/api/webhooks/v1/) - Manage webhooks, list event notifications, and more. * Webhook events * [Checkout webhook events](/api/rest/webhooks/event-names/#checkout-buyer-approval) - Checkout buyer approval-related webhooks. * [Order webhook events](/api/rest/webhooks/event-names/) - Other order-related webhooks. * [Show order details endpoint](/api/orders/v2/orders-get/) - Determine the status of an order. ### Sample PAYMENT.CAPTURE.COMPLETED webhook [#sample-paymentcapturecompleted-webhook]
```json lineNumbers { "id": "WH-9LK14475MF9937440-9EG47645TP521822L", "event_version": "1.0", "create_time": "2022-05-10T06:04:12.533Z", "resource_type": "capture", "resource_version": "2.0", "event_type": "PAYMENT.CAPTURE.COMPLETED", "summary": "Payment completed for EUR 100.0 EUR", "resource": { "amount": { "value": "100.00", "currency_code": "EUR" }, "supplementary_data": { "related_ids": { "order_id": "5V159329PV571861D" } }, "update_time": "2022-01-19T06:04:08Z", "create_time": "2022-01-19T06:04:08Z", "final_capture": true, "seller_receivable_breakdown": { "paypal_fee": { "value": "3.80", "currency_code": "EUR" }, "gross_amount": { "value": "100.00", "currency_code": "EUR" }, "net_amount": { "value": "96.20", "currency_code": "EUR" } }, "custom_id": "Custom-1234", "invoice_id": "Invoice-12345", "links": [ { "method": "GET", "rel": "self", "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J" }, { "method": "POST", "rel": "refund", "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund" }, { "method": "GET", "rel": "up", "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D" } ], "id": "5R102774VL663561J", "status": "COMPLETED" }, "links": [ { "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L", "rel": "self", "method": "GET" }, { "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend", "rel": "resend", "method": "POST" } ] } ``` > **Note:** **Note:** The order ID from **Step 2** should match the `resource.supplementary_data.related_ids.order_id` parameter in the webhook payload. ### Sample PAYMENT.CAPTURE.DENIED webhook [#sample-paymentcapturedenied-webhook]
```json lineNumbers { "id": "WH-9LK14475MF9937440-9EG47645TP521822L", "event_version": "1.0", "create_time": "2022-05-10T06:04:12.533Z", "resource_type": "capture", "resource_version": "2.0", "event_type": "PAYMENT.CAPTURE.DENIED", "summary": "Payment denied for EUR 100.0 EUR", "resource": { "amount": { "value": "100.00", "currency_code": "EUR" }, "supplementary_data": { "related_ids": { "order_id": "5V159329PV571861D" } }, "update_time": "2022-05-10T06:04:08Z", "create_time": "2022-05-10T06:04:08Z", "final_capture": true, "seller_receivable_breakdown": { "paypal_fee": { "value": "3.80", "currency_code": "EUR" }, "gross_amount": { "value": "100.00", "currency_code": "EUR" }, "net_amount": { "value": "96.20", "currency_code": "EUR" } }, "links": [ { "method": "GET", "rel": "self", "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J" }, { "method": "POST", "rel": "refund", "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund" }, { "method": "GET", "rel": "up", "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D" } ], "id": "5R102774VL663561J", "status": "DECLINED" }, "links": [ { "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L", "rel": "self", "method": "GET" }, { "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend", "rel": "resend", "method": "POST" } ] } ``` > **Note:** **Note:** The order ID from **Step 2** should match the `resource.supplementary_data.related_ids.order_id` parameter in the webhook payload. Alternatively, you can get the order capture result from the [Show order details](/api/orders/v2/orders-get/) endpoint. > **Note:** **Important:** Exercise caution when polling for order capture result using the [Show order details](/api/orders/v2/orders-get/) endpoint. PayPal enforces rate limits on API requests. ### Sample request [#sample-request-1]
```bash lineNumbers curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " ``` ### Sample response [#sample-response-1]
```json lineNumbers { "id": "5V159329PV571861D", "intent": "CAPTURE", "status": "COMPLETED", "payment_source": { "bancomatpay": { "name": "Firstname Lastname", "country_code": "PT" } }, "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL", "purchase_units": [ { "reference_id": "default", "amount": { "currency_code": "EUR", "value": "100.00" }, "payments": { "captures": [ { "id": "5R102774VL663561J", "status": "COMPLETED", "amount": { "currency_code": "EUR", "value": "100.00" }, "final_capture": true, "seller_receivable_breakdown": { "gross_amount": { "currency_code": "EUR", "value": "100.00" }, "paypal_fee": { "currency_code": "EUR", "value": "3.80" }, "net_amount": { "currency_code": "EUR", "value": "96.20" } }, "links": [ { "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J", "rel": "self", "method": "GET" }, { "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund", "rel": "refund", "method": "POST" }, { "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D", "rel": "up", "method": "GET" } ] } ] } } ], "links": [ { "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D", "rel": "self", "method": "GET" } ] } ``` ### Step result [#step-result-1] A successful request returns the HTTP `200 OK` status code with a JSON response body that returns a `COMPLETED` status. A successfully captured order has the following: * The order status as `COMPLETED`, which means the order was captured successfully. * A capture with `COMPLETED` status is present in the response parameter `purchase_units[0].payments.captures[0]`. * The `up` HATEOAS link indicates the order associated with this capture. ## 4. Notify buyer of success [#4-notify-buyer-of-success] After a successful payment, notify the buyer of a successful transaction. You can do this by sending a confirmation email. ## Next steps [#next-steps] * [Test your integration in PayPal Sandbox](/sandbox-testing/overview) Use these buyer phone numbers to simulate the failure scenarios in the PayPal sandbox environment. | Scenario | Buyer phone national\_number | | --------------------------------------------------------------- | ---------------------------- | | `The phone number provided is not associated with BANCOMAT Pay` | `111111111` | | `The buyer has canceled/denied the payment` | `222222222` | Any buyer phone number not listed in the table will simulate a successful scenario in the PayPal sandbox environment. * [Go live in PayPal's production environment](/api/rest/production/).