Integrate Multibanco using Orders API

DOCSCURRENT

Last updated: Jan 31st, 1:06am

Know before you code

Request approval to enable Multibanco by visiting these sandbox and live links:
- Sandbox: https://www.sandbox.paypal.com/bizsignup/entry?product=multibanco&capabilities=MULTIBANCO&country.x=<merchant's country>
- Live: https://www.paypal.com/bizsignup/add-product?product=multibanco&capabilities=MULTIBANCO&country.x=<merchant's country>

Partners: Be sure to onboard your merchants upfront, before they accept payments. Onboarding after making payments, specifically Progressive Onboarding, isn't supported for alternative payment methods.

Note: The integration steps for implementing alternative payment methods are similar. If you've integrated another alternative payment method before, you can reuse that code with adjustments for this payment method.

Make sure you're subscribed to the following webhook events:
- PAYMENT.CAPTURE.PENDING – Listen for this webhook as an indication that payment initiation was successful, the payment is in a pending state, and is waiting for the buyer to complete the payment.
- PAYMENT.CAPTURE.COMPLETED – Listen for this webhook as an indication that the buyer has completed the payment, which can take up to seven days. You can ship the order to the buyer at this point.
- PAYMENT.CAPTURE.DENIED - Listen for this webhook as an indication that the Multibanco payment instruction has expired or the payer didn't complete the payment on time. You can cancel the order at this point.
  After you receive 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.

Make sure your preference for receiving payments in your PayPal business or merchant account is set to accept and convert to the currency in your account. In your profile, select Account Settings > Payment preferences > Block payments and click Update to mark this preference.

When processing Multibanco payments, you don't need to capture payment for the order.

Offer Multibanco on the checkout page

You'll need to create the user interface to offer Multibanco and collect the buyer's information, then you'll use the API calls described in the remainder of this topic to:

create the order

specify Multibanco as the payment method

present Multibanco payment instruction to the buyer

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

Create an order

Use the buyer information you captured from your user interface to create an order.

API endpoint used: Create order

Sample request
Sample response

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <Access-Token>" \
4-d '{
5    "intent": "CAPTURE",
6    "purchase_units": [
7        {
8            "amount": {
9                "currency_code": "EUR",
10                "value": "100.00"
11            }
12        }
13    ]
14}'

Modify the code

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

Access-Token - Your access token.

intent - To use an alternative payment method, this parameter must be set to CAPTURE as it is in this sample code.

purchase_units[0].amount - Pass the value of the order and the currency code.

Optional: 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 201 Created.

A JSON response body that contains the order ID. You'll use the order ID in the next step.

Specify Multibanco as the payment method

To specify Multibanco as the payment method the buyer selected in your user interface, confirm the payment source for the order.

Orders API endpoint used: Confirm the Order

Sample request
Sample response

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/54K10082DX701193V/confirm-payment-source \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <Access-Token>" \
4-d '{
5    "payment_source": {
6        "multibanco": {
7            "name": "John Doe",
8            "country_code": "PT"
9        }
10    },
11    "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
12    "application_context": {
13        "locale": "en-PT",
14        "return_url": "https://example.com/returnUrl",
15        "cancel_url": "https://example.com/cancelUrl"
16    }
17}'

Modify the code

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

Access-Token - Your access token.

Order ID - In the URI for the API call, replace the sample ID with your order ID. In the sample, the order ID is 54K10082DX701193V.

payment_source - Specify the following:
- multibanco as the payment_source.
- PT as the country_code.
- Account holder's full name on name field.

processing_instruction - Set this value to ORDER_COMPLETE_ON_PAYMENT_APPROVAL for processing Multibanco payments.

application_context - Specify the preferred language for returned errors, the URL the buyer is returned to after approving the purchase with their selected payment method, and the URL the buyer is returned to after canceling an approval with their selected payment method.
Note: While return_url and cancel_url are optional fields, this integration requires you specify them to handle the handoff from the payment method back to your site. You can use the cancel_url to redirect buyers when an error occurs while they're on the payment method's site, so make sure your cancel URL works for that situation as well as an actual cancellation by the buyer.

Step result

A successful request results in the following:

A return status code of HTTP 200 OK.

A JSON response body that contains order details and HATEOAS links. You'll use the payer-action redirect in the next step. See also: HATEOAS links.

Present Multibanco payment instruction to the buyer

In your user interface, attach the payer-action redirect returned in the Confirm payment source call to the Multibanco payment button. This renders the Multibanco payment instruction.

In the sample, the redirect is: "https://www.sandbox.paypal.com/payment/multibanco?token=54K10082DX701193V".

You can also send the Multibanco payment instruction to your buyers in an email. Obtain the details from Show order details endpoint. References to the payment instruction are present in the payment_source.multibanco.payment_reference and payment_source.multibanco.payment_entity response parameter.

Sample request
Sample response

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

Modify the code

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

Access-Token - Your access token.

Order ID - In the URI for the API call, replace the sample ID with your Order ID. In the sample, the Order ID is 54K10082DX701193V.

Step result

A successful request returns the HTTP 200 OK status code with a JSON response body that returns a COMPLETED status.

A successful approval results in the following:

The order status changes to COMPLETED, which means the order was created successfully.

A capture with PENDING status is present in the response parameter purchase_units[0].payments.captures[0]. The up HATEOAS link indicates the order associated with this capture.

The PAYMENT.CAPTURE.PENDING webhook event is triggered, which indicates that payment initiation was successful, the payment is in a pending state, and is waiting for the buyer to complete the payment.
- Wait for the buyer to complete the payment, which might take up to seven days.
- Send a payment confirmation to the buyer with Multibanco payment_reference and payment_entity.

Sample PAYMENT.CAPTURE.PENDING webhook

1{
2  "id": "WH-3XD97656HT346122M-81M194208A0322526",
3  "event_version": "1.0",
4  "create_time": "2021-06-16T22:52:21.351Z",
5  "resource_type": "capture",
6  "resource_version": "2.0",
7  "event_type": "PAYMENT.CAPTURE.PENDING",
8  "summary": "Payment pending for EUR 100.0 EUR",
9  "resource": {
10    "amount": {
11      "value": "100.00",
12      "currency_code": "EUR"
13    },
14    "seller_protection": {
15      "dispute_categories": [
16        "ITEM_NOT_RECEIVED",
17        "UNAUTHORIZED_TRANSACTION"
18      ],
19      "status": "ELIGIBLE"
20    },
21    "supplementary_data": {
22      "related_ids": {
23        "order_id": "54K10082DX701193V"
24      }
25    },
26    "update_time": "2021-06-16T22:52:17Z",
27    "create_time": "2021-06-16T22:52:17Z",
28    "final_capture": true,
29    "links": [
30      {
31        "method": "GET",
32        "rel": "self",
33        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/6AS86814R5412231H"
34      },
35      {
36        "method": "POST",
37        "rel": "refund",
38        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/6AS86814R5412231H/refund"
39      },
40      {
41        "method": "GET",
42        "rel": "up",
43        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/54K10082DX701193V"
44      }
45    ],
46    "id": "6AS86814R5412231H",
47    "status_details": {
48      "reason": "OTHER"
49    },
50    "status": "PENDING"
51  },
52  "links": [
53    {
54      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-3XD97656HT346122M-81M194208A0322526",
55      "rel": "self",
56      "method": "GET"
57    },
58    {
59      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-3XD97656HT346122M-81M194208A0322526/resend",
60      "rel": "resend",
61      "method": "POST"
62    }
63  ]
64}

Fulfill the order

When the buyer completes the payment, PAYMENT.CAPTURE.COMPLETED webhook event is triggered, which indicates that payment completion was successful and you can fulfill the order.

Look for one of the following webhooks:

PAYMENT.CAPTURE.COMPLETED – This webhook is an indication that the buyer has completed the payment, which can take up to seven days to complete. You can ship the order to the buyer at this point.

PAYMENT.CAPTURE.DENIED - This webhook is an indication that the Multibanco payment has expired or the buyer didn't complete the payment successfully. You should not fulfill the order.

Sample PAYMENT.CAPTURE.COMPLETED
Sample PAYMENT.CAPTURE.DENIED

1{
2  "id": "WH-6G192137AT164274E-1WK039370M324962E",
3  "event_version": "1.0",
4  "create_time": "2021-06-16T22:53:25.068Z",
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    "seller_protection": {
15      "dispute_categories": [
16        "ITEM_NOT_RECEIVED",
17        "UNAUTHORIZED_TRANSACTION"
18      ],
19      "status": "ELIGIBLE"
20    },
21    "supplementary_data": {
22      "related_ids": {
23        "order_id": "54K10082DX701193V"
24      }
25    },
26    "update_time": "2021-06-16T22:53:11Z",
27    "create_time": "2021-06-16T22:52:17Z",
28    "final_capture": true,
29    "seller_receivable_breakdown": {
30      "paypal_fee": {
31        "value": "2.25",
32        "currency_code": "EUR"
33      },
34      "gross_amount": {
35        "value": "100.00",
36        "currency_code": "EUR"
37      },
38      "net_amount": {
39        "value": "97.75",
40        "currency_code": "EUR"
41      }
42    },
43    "links": [
44      {
45        "method": "GET",
46        "rel": "self",
47        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/6AS86814R5412231H"
48      },
49      {
50        "method": "POST",
51        "rel": "refund",
52        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/6AS86814R5412231H/refund"
53      },
54      {
55        "method": "GET",
56        "rel": "up",
57        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/54K10082DX701193V"
58      }
59    ],
60    "id": "6AS86814R5412231H",
61    "status": "COMPLETED"
62  },
63  "links": [
64    {
65      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-6G192137AT164274E-1WK039370M324962E",
66      "rel": "self",
67      "method": "GET"
68    },
69    {
70      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-6G192137AT164274E-1WK039370M324962E/resend",
71      "rel": "resend",
72      "method": "POST"
73    }
74  ]
75}

Step result

A successful request results in the following:

If the payment completion by the payer is successful, the capture status changes to COMPLETED and you can ship the order.

If the buyer is unable to complete the payment successfully, the capture status changes to DENIED.

Send a confirmation email to the buyer.

Next steps

Required
Test integration

Test the integration in the PayPal sandbox environment.

Required
Go live

Take your application live in the PayPal production environment once testing is successful.