Pro Checkout

Introduction

Integrating with the ProCheckout API brings frictionless payments to your web site. MEO Wallet handles all the complexity of dealing with different payment providers and gives you a single workflow to accept payments. You also get a single API for Web, Mobile and other channels such as MEO Interactive TV.

The workflow is simple

Pro Checkout Workflow

After getting your authentication token, you start by calling /api/v2/checkout to initialize the checkout process with your parameters. Like this:

  curl https://services.wallet.pt/api/v2/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: WalletPT 7a0eb41208209639eda9bf765b6cb04d59fb9e34" \
  -d '{"payment":{ "client": {
                   "name": "John Santos",
                   "email": "jsantos@email.com",
                   "address": {
                         "country": "pt",
                         "address":"Av. Fontes Pereira de Melo",
                         "city": "Lisboa",
                         "postalcode": "1100-000"
                    }
                  },
                 "amount":229.73,
                 "currency": "EUR",
                 "items":[{
                           "ref":123,
                           "name":"Somny DX-200",
                           "descr":"Photo Camera",
                           "qt":1
                          }],
                                   "ext_invoiceid": "C12423324"
                  },
      "url_confirm":"https://example.com/shop/confirm",
      "url_cancel":"https://example.com/shop/cancel"}'

MEO Wallet returns:

{
    "id": "81ae8d9a-f03a-42f8-8464-442a679d13db",
    "url_confirm": "https://example.com/shop/confirm?checkoutid=81ae8d9a-f03a-42f8-8464-442a679d13db",
    "url_cancel": "https://example.com/shop/cancel?checkoutid=81ae8d9a-f03a-42f8-8464-442a679d13db",
    "payment": {
        "currency": "EUR",
        "ipaddress": "194.65.5.225",
        "type": "PAYMENT",
        "status": "NEW",
        "channel": "WEBSITE",
        "notes": "",
        "user_notes": "",
        "items": [
            {
                "descr": "Photo Camera",
                "ref": 123,
                "name": "Somny DX-200",
                "qt": 1
            }
        ],
        "refundable": false,
        "fee": 0,
        "amount": 229.73,
        "amount_net": 229.73,
        "client": {
            "name": "John Santos",
            "email": "jsantos@email.com",
            "address": {
                "address": "Av. Fontes Pereira de Melo",
                "city": "Lisboa",
                "postalcode": "1100-000",
                "country": "pt"
            }
        },
        "merchant": {
            "id": 1443,
            "name": "Shoppp",
            "email": "support@shoppp.pt"
        },
        "ext_invoiceid": "C12423324",
        "date": "2014-03-27T15:18:09+0000",
        "modified_date": "2014-03-27T15:18:10+0000"
    },
    "url_redirect": "https://wallet.pt/checkout/81ae8d9a-f03a-42f8-8464-442a679d13db",
}

Then you redirect the user to wallet.pt using the provided url_redirect URL. When all payments details are handled MEO Wallet redirects your customer back to your website using the URLs you provided. If everything goes well you will then receive a callback on your platform signaling the money is safely in your wallet. For some payment methods which require users to take extra actions (like Multibanco, an asynchronous payment method) you might receive more callbacks notifying the payment process is pending user action.

To know more more about callbacks click here.

Don't overlook the optional fields

The API provides you with a number of optional fields you can use to make your store simpler, help the customer and help yourself.

The items field gives extra context to the user during the payment phase and makes customer support easier when you're looking at transaction details.

The ext_customerid, ext_invoiceid and ext_email help you with connecting payments with your sales. Passing your identifiers on this fields allows you to integrate MEO Wallet without even changing your database schemas. Just look up your own client or invoice id when you receive a callback or list payments.

Integration into your website

MEO Wallet provides visual resources for easy integration into your website in the form of secure payments label which you should include in your website's footer and premade payment button images to use in your checkout page. You can use the auxilary get payment methods API call to ensure the methods you are showing your customers are up to date.

Controlling the checkout page

If you want to keep your web site simple MEO Wallet can ask your customer for name, email, phone number and shipping address. This is configured using required_fields on the Checkout structure. You can provide defaults for this information on the operation's Client Data structure which is also where you find the information filled in by your customer.

You can also fill the Payment Item structure in Checkout to give your customer a payment smoother flow by keeping information about what they are buying on screen.

The MEO Wallet website defaults to the portuguese language but follows the browser prefered language. However, if your website supports multiple langagues you can achieve continuity by passing the locale parameter on the checkout URL (url_redirect) query string.

For example, if you get:

https://wallet.pt/checkout/81ae8d9a-f03a-42f8-8464-442a679d13db

You can programmatically change it by adding the locale=lang parameter on your frontend just before doing the actual redirection:

https://wallet.pt/checkout/81ae8d9a-f03a-42f8-8464-442a679d13db?locale=en_US

Currently the pt_PT and en_US locales are supported.

Security and fraud detection

Even if you don't want us to collect customer data for you should still pass customer order information on your checkout request. We use these data in our fraud detection systems and having it makes us more capable of protecting you against fraudulent transactions. This doesn't mean your business should not do its own fraud detection but that we try to provide an extra line of defense.

Here's our official security page for more information and good pratices (in Portuguese).

Other integration scenarios

If you have mobile face-to-face or interactive TV scenarios please contact us. We have specific integration architectures for those scenarios.