BANCOMAT Pay

DOCSBeta

Last updated: Sept 19th, 3:18am

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

Your checkout page offers alternative payment methods.

Buyer provides their personal details and selects an alternative payment method from your checkout page.

Buyer is transferred from your checkout page to the third-party bank to confirm the purchase.

Buyer authorizes and confirms payment.

Buyer returns to your site to see confirmation of purchase.

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

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

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:
- The PAYMENT.CAPTURE.COMPLETED webhook event indicates a successful order capture.
- The PAYMENT.CAPTURE.DENIED webhook event indicate a failed order capture.

Upon receiving each webhook, fetch the latest order details using Show order details. 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

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 fulfill the payment.

(Optional) brand_name is supported in create order.

Refer to Payment method icons for icons you can use and download locations.

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

API endpoint used: Create order

1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <Access-Token>' \
4--header 'PayPal-Request-Id: <PayPal-RequestId>' \
5--data-raw '{
6    "intent": "CAPTURE",
7    "payment_source": {
8        "bancomatpay": {
9            "country_code": "IT",
10            "name": "Firstname Lastname",
11            "phone": {
12              "national_number": "1234567890",
13              "country_code": "39",
14            },
15            "experience_context": {
16              "brand_name": "brand name override"
17            }
18        }
19    },
20    "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
21    "purchase_units": [
22        {
23            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
24            "amount": {
25                "currency_code": "EUR",
26                "value": "100.00"
27            }
28        }
29    ]
30}'

Modify the code

After you copy the code in the sample request, modify the following:

Access-Token - Your access token.

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.

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: Change or add other parameters in the Create order request body to create an order that reflects the actual order details.

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.

Sample response

1{
2    "id": "5V159329PV571861D",
3    "status": "PAYER_ACTION_REQUIRED",
4    "payment_source": {
5        "bancomatpay": {
6            "name": "Firstname Lastname",
7            "country_code": "IT"
8        }
9    },
10    "links": [
11        {
12            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
13            "rel": "self",
14            "method": "GET"
15        }
16    ]
17}

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

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 endpoint to determine the status of an order.
- The up HATEOAS link indicates the order associated with this capture.

See Subscribe to checkout webhooks for more information.

Here are some additional resources as you create webhook handler code:

Webhook Management API - Manage webhooks, list event notifications, and more.

Webhook events
- Checkout webhook events - Checkout buyer approval-related webhooks.
- Order webhook events - Other order-related webhooks.

Show order details endpoint - Determine the status of an order.

Sample PAYMENT.CAPTURE.COMPLETED webhook

1{
2  "id": "WH-9LK14475MF9937440-9EG47645TP521822L",
3  "event_version": "1.0",
4  "create_time": "2022-05-10T06:04:12.533Z",
5  "resource_type": "capture",
6  "resource_version": "2.0",
7  "event_type": "PAYMENT.CAPTURE.COMPLETED",
8  "summary": "Payment completed for EUR 100.0 EUR",
9  "resource": {
10    "amount": {
11      "value": "100.00",
12      "currency_code": "EUR"
13    },
14    "supplementary_data": {
15      "related_ids": {
16        "order_id": "5V159329PV571861D"
17      }
18    },
19    "update_time": "2022-01-19T06:04:08Z",
20    "create_time": "2022-01-19T06:04:08Z",
21    "final_capture": true,
22    "seller_receivable_breakdown": {
23      "paypal_fee": {
24        "value": "3.80",
25        "currency_code": "EUR"
26      },
27      "gross_amount": {
28        "value": "100.00",
29        "currency_code": "EUR"
30      },
31      "net_amount": {
32        "value": "96.20",
33        "currency_code": "EUR"
34      }
35    },
36    "custom_id": "Custom-1234",
37    "invoice_id": "Invoice-12345",
38    "links": [
39      {
40        "method": "GET",
41        "rel": "self",
42        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J"
43      },
44      {
45        "method": "POST",
46        "rel": "refund",
47        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund"
48      },
49      {
50        "method": "GET",
51        "rel": "up",
52        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D"
53      }
54    ],
55    "id": "5R102774VL663561J",
56    "status": "COMPLETED"
57  },
58  "links": [
59    {
60      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L",
61      "rel": "self",
62      "method": "GET"
63    },
64    {
65      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend",
66      "rel": "resend",
67      "method": "POST"
68    }
69  ]
70}

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

1{
2  "id": "WH-9LK14475MF9937440-9EG47645TP521822L",
3  "event_version": "1.0",
4  "create_time": "2022-05-10T06:04:12.533Z",
5  "resource_type": "capture",
6  "resource_version": "2.0",
7  "event_type": "PAYMENT.CAPTURE.DENIED",
8  "summary": "Payment denied for EUR 100.0 EUR",
9  "resource": {
10    "amount": {
11      "value": "100.00",
12      "currency_code": "EUR"
13    },
14    "supplementary_data": {
15      "related_ids": {
16        "order_id": "5V159329PV571861D"
17      }
18    },
19    "update_time": "2022-05-10T06:04:08Z",
20    "create_time": "2022-05-10T06:04:08Z",
21    "final_capture": true,
22    "seller_receivable_breakdown": {
23      "paypal_fee": {
24        "value": "3.80",
25        "currency_code": "EUR"
26      },
27      "gross_amount": {
28        "value": "100.00",
29        "currency_code": "EUR"
30      },
31      "net_amount": {
32        "value": "96.20",
33        "currency_code": "EUR"
34      }
35    },
36    "links": [
37      {
38        "method": "GET",
39        "rel": "self",
40        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J"
41      },
42      {
43        "method": "POST",
44        "rel": "refund",
45        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund"
46      },
47      {
48        "method": "GET",
49        "rel": "up",
50        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D"
51      }
52    ],
53    "id": "5R102774VL663561J",
54    "status": "DECLINED"
55  },
56  "links": [
57    {
58      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L",
59      "rel": "self",
60      "method": "GET"
61    },
62    {
63      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend",
64      "rel": "resend",
65      "method": "POST"
66    }
67  ]
68}

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 endpoint.

Important: Exercise caution when polling for order capture result using the Show order details endpoint. PayPal enforces rate limits on API requests.

Sample request

1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer <Access-Token>"

Sample response

1{
2  "id": "5V159329PV571861D",
3  "intent": "CAPTURE",
4  "status": "COMPLETED",
5  "payment_source": {
6    "bancomatpay": {
7      "name": "Firstname Lastname",
8      "country_code": "PT"
9    }
10  },
11  "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
12  "purchase_units": [
13    {
14      "reference_id": "default",
15      "amount": {
16        "currency_code": "EUR",
17        "value": "100.00"
18      },
19      "payments": {
20        "captures": [
21          {
22            "id": "5R102774VL663561J",
23            "status": "COMPLETED",
24            "amount": {
25              "currency_code": "EUR",
26              "value": "100.00"
27            },
28            "final_capture": true,
29            "seller_receivable_breakdown": {
30              "gross_amount": {
31                "currency_code": "EUR",
32                "value": "100.00"
33              },
34              "paypal_fee": {
35                "currency_code": "EUR",
36                "value": "3.80"
37              },
38              "net_amount": {
39                "currency_code": "EUR",
40                "value": "96.20"
41              }
42            },
43            "links": [
44              {
45                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J",
46                "rel": "self",
47                "method": "GET"
48              },
49              {
50                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund",
51                "rel": "refund",
52                "method": "POST"
53              },
54              {
55                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
56                "rel": "up",
57                "method": "GET"
58              }
59            ]
60          }
61        ]
62      }
63    }
64  ],
65  "links": [
66    {
67      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
68      "rel": "self",
69      "method": "GET"
70    }
71  ]
72}

Step result

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

After a successful payment, notify the buyer of a successful transaction. You can do this by sending a confirmation email.

Next steps

Test your integration in PayPal Sandbox

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.