Prows 2 API - Credit Card Payments

This is an extension only available to partner merchants.

The Prows 2 Credit Card API allows merchants to:

  • Create credit card payments without using a MEO Wallet checkout.

  • Store credit cards using a tokenization service.

If you are a PCI DSS certified merchant you can collect the card data yourself and send it through the API as is.

If that’s not the case you must use the Secure Form Fields. That will encrypt card data on MEO Wallet side. You will then pass the encrypted data to the API.

Pre-requisites

Before using this API, you will need:

  • A merchant account which will receive payments. You can create an account here.
  • A merchant API key. You can generate one at “O Meu Negócio->Chaves de API” option in the merchant backoffice sidebar.
  • A ESB Token (will be provided by the Altice Pay team).

Authentication

The access to the API is based in a custom HTTP Basic authentication. Details here.

You must provide an extra HTTP header named “Proxy-Authorization” with a value with this prefix: ESBToken=. The value of this token will be provided as described above.

Services

Check examples below for each service. The endpoint used in these examples is from the sandbox environment.

The production endpoint is: https://services.wallet.pt

Anonymous Credit Card Payment

This is the easiest way of generate credit card payments. You only need to pass the card data in a single step.

This service creates a credit card payment providing the card data, namely, the number the validity date and the vcode (CVV).

The customer needs to perform a 3-DSecure 2 authentication using the returned “cardsecure_url_redirect” to complete the payment.

You can pass a request_id in the payload to track this request. Check this page for details.

Request POST /prows/v2/payment
Query params none
Data params Operation
Returns Operation
Click here for an example
curl --location --request POST 'https://services.sandbox.meowallet.pt/prows/v2/payment' \
--header 'Authorization: WalletPT <merchant-wallet-API-Key>' \
--header 'Content-Type: application/json' \
--header 'Proxy-Authorization: ESB Token=<ESB-Token>' \
--data-raw '{
    "callback": "https://example.com",
    "cardsecure_url_confirm": "http://www.example.com",
    "cardsecure_url_cancel": "http://www.sapo.pt",
    "newCard": {
        "address": {
            "address": "picoas em lisboa",
            "city": "na",
            "postalcode": "1100-100"
        },
        "number": "5204730000001011",
        "name": "João Rocha",
        "vcode": "123",
        "valdate": "12/2025",
        "mode": "USER"
    },
    "method": "CC",
    "amount":1.5,
    "currency": "EUR",
    "ext_invoiceid":"pista",
    "ext_email":"sergio@telecom.pt",
    "ext_customerid":"Xavi"
}'
Response example:
{
    "card": {
        "token": "A111F938-BD19-11ED-A054-D5C92C1F1442",
        "last4": "1011",
        "type": "mastercard",
        "valdate": "12/2025",
        "expired": false
    },
    "cardsecure_url_confirm": "http://www.example.com",
    "cardsecure_url_cancel": "http://www.sapo.pt",
    "currency": "EUR",
    "id": "34f634c1-d5ca-4c9c-953a-a9e2a13672ce",
    "ipaddress": "10.134.167.217",
    "ext_invoiceid": "PT12345",
    "ext_email": "joao@telecom.pt",
    "ext_customerid": "PT1234",
    "type": "PAYMENT",
    "channel": "WEBSITE",
    "modified_date": "2023-03-07T18:55:33+0000",
    "notes": "",
    "user_notes": "",
    "cardsecure_url_redirect": "https://sandbox.meowallet.pt/3ds/34f634c1-d5ca-4c9c-953a-a9e2a13672ce",
    "refundable": false,
    "fee": -1.02,
    "amount": 1.5,
    "amount_net": 0.48,
    "merchant": {
        "id": "600000000",
        "name": "testmerchant",
        "email": "testmerchant@telecom.pt"
    },
    "date": "2023-03-07T18:55:29+0000",
    "method": "CC",
    "status": "PENDING"
}


Click here for an example using encrypted card data
curl --location --request POST 'https://services.sandbox.meowallet.pt/prows/v2/payment' \
--header 'Authorization: WalletPT <merchant-wallet-API-Key>' \
--header 'Content-Type: application/json' \
--header 'Proxy-Authorization: ESB Token=<ESB-Token>' \
--data-raw '{
    "callback": "https://example.com",
    "cardsecure_url_confirm": "http://www.example.com",
    "cardsecure_url_cancel": "http://www.sapo.pt",
    "newCardSecure": {
        "address": {
            "address": "picoas em lisboa",
            "city": "na",
            "postalcode": "1100-100"
        },
        "number": "V00019b1FrSa8IZnJ0rk1Wvwzi+XNfS1zJMUPLWoPvaxBkTnM+6f66qLALMtCBmn/P1rzWnasbpgI9lHV2yuRbuRh2akdxf1eBR41mUe+Z7SnpwU=|201900",
        "name": "V0001lge7ForV9baDpYZKJSOOMja8aKYyLLxxGnc+xb5Ql4Zpf7y64NHMzQL3eCKIPLSygTd4LTWYGKBf0QMZmV6uwg==|201900",
        "vcode": "V0001cZEk5Ldf0/4U3cSctouoYySgPIE6TZ+mso/UL8FVybTWkIO6j5S0scP8O7dI3uwZcL7/P5cqOnAskDK6UYZKcw==|201900",
        "valdate": "V0001MhxA0+/q9UuKmWTuo6X22fB1TkUtzcXiNrA5agdxZuRLnmHgMCHMobn5EdQWXo3qCNZNrPleeBmGk93Af1gAmA==|201900"
    },
    "method": "CC",
    "amount":1.5,
    "currency": "EUR",
    "ext_invoiceid":"pista",
    "ext_email":"sergio@telecom.pt",
    "ext_customerid":"Xavi"
}'
Response example:
{
    "card": {
        "token": "A111F938-BD19-11ED-A054-D5C92C1F1442",
        "last4": "1011",
        "type": "mastercard",
        "valdate": "12/2025",
        "expired": false
    },
    "cardsecure_url_confirm": "http://www.example.com",
    "cardsecure_url_cancel": "http://www.sapo.pt",
    "currency": "EUR",
    "id": "34f634c1-d5ca-4c9c-953a-a9e2a13672ce",
    "ipaddress": "10.134.167.217",
    "ext_invoiceid": "PT12345",
    "ext_email": "joao@telecom.pt",
    "ext_customerid": "PT1234",
    "type": "PAYMENT",
    "channel": "WEBSITE",
    "modified_date": "2023-03-07T18:55:33+0000",
    "notes": "",
    "user_notes": "",
    "cardsecure_url_redirect": "https://sandbox.meowallet.pt/3ds/34f634c1-d5ca-4c9c-953a-a9e2a13672ce",
    "refundable": false,
    "fee": -1.02,
    "amount": 1.5,
    "amount_net": 0.48,
    "merchant": {
        "id": "600000000",
        "name": "testmerchant",
        "email": "testmerchant@telecom.pt"
    },
    "date": "2023-03-07T18:55:29+0000",
    "method": "CC",
    "status": "PENDING"
}


Add Credit Card

This service allows the storage of a credit card to be used in payments later. Please note that you must provide a unique request_id to relate your request with the callback containing the 3-D Secure 2 authentication result. MEO Wallet offers a special feature to store cards using encrypted card data for merchants without a PCI DSS certification.

Request POST /prows/v2/creditcard
Query params none
Data params StoreCardRequest
Returns CreditCard or CardSecureResponse
Click here for an example for a PCI DSS merchant
curl --location --request POST 'https://services.sandbox.meowallet.pt/prows/v2/creditcard' \
--header 'Authorization: WalletPT <merchant-wallet-API-Key>' \
--header 'Content-Type: application/json' \
--header 'Proxy-Authorization: ESB Token=<ESB-Token>' \
--data-raw '{
    "newCard": {
        "address": {
            "address":"avenida de cima",
            "city": "lisboa",
            "postalcode": "1100-100"
        },
        "number": "4018810001010010",
        "name": "Test test",
        "vcode": "090",
        "valdate": "12/2025"
    },
    "cardsecure_url_confirm": "http://www.example.com",
    "cardsecure_url_cancel": "http://www.sapo.pt",
    "request_id": "<uuid>"
}'
If a 3-D Secure 2 authentication is required, you will get a response like this:
{
    "cardsecure_url_redirect": "https://sandbox.meowallet.pt/3ds/33020eca-f981-11ed-aaa5-e183f5cf2760"
}
Redirect your customer to the URL above. Otherwise, you will get the card token data, as follows:
{
    "verification_status": "VERIFIED",
    "token": "92F0F59E-F4C7-11ED-BF8B-FA83F5CF2760",
    "last4": "0010",
    "bin": "401881",
    "type": "visa",
    "name": "Test test",
    "valdate": "12/2025",
    "voided": false,
    "expired": false
}
Click here for an example using encrypted card data
curl --location --request POST 'https://services.sandbox.meowallet.pt/prows/v2/creditcard' \
--header 'Authorization: WalletPT <merchant-wallet-API-Key>' \
--header 'Content-Type: application/json' \
--header 'Proxy-Authorization: ESB Token=<ESB-Token>' \
--data-raw '{
    "newCardSecure": {
        "address": {
            "address":"avenida de cima",
            "city": "lisboa",
            "postalcode": "1100-100"
        },
        "number": "V00019b1FrSa8IZnJ0rk1Wvwzi+XNfS1zJMUPLWoPvaxBkTnM+6f66qLALMtCBmn/P1rzWnasbpgI9lHV2yuRbuRh2akdxf1eBR41mUe+Z7SnpwU=|201900",
        "name": "V0001lge7ForV9baDpYZKJSOOMja8aKYyLLxxGnc+xb5Ql4Zpf7y64NHMzQL3eCKIPLSygTd4LTWYGKBf0QMZmV6uwg==|201900",
        "vcode": "V0001cZEk5Ldf0/4U3cSctouoYySgPIE6TZ+mso/UL8FVybTWkIO6j5S0scP8O7dI3uwZcL7/P5cqOnAskDK6UYZKcw==|201900",
        "valdate": V0001MhxA0+/q9UuKmWTuo6X22fB1TkUtzcXiNrA5agdxZuRLnmHgMCHMobn5EdQWXo3qCNZNrPleeBmGk93Af1gAmA==|201900"
    },
    "cardsecure_url_confirm": "http://www.example.com",
    "cardsecure_url_cancel": "http://www.sapo.pt",
    "request_id": "<uuid>"
}'
If a 3-D Secure 2 authentication is required, you will get a response like this:
{
    "cardsecure_url_redirect": "https://sandbox.meowallet.pt/3ds/33020eca-f981-11ed-aaa5-e183f5cf2760"
}
Redirect your customer to the URL above. Otherwise, you will get the card token data, as follows:
{
    "verification_status": "VERIFIED",
    "token": "92F0F59E-F4C7-11ED-BF8B-FA83F5CF2760",
    "last4": "0010",
    "bin": "401881",
    "type": "visa",
    "name": "Test test",
    "valdate": "12/2025",
    "voided": false,
    "expired": false
}


A callback will be sent to the configured URL in your Wallet with the 3-D Secure 2 authentication result. This callback is sent even if the credit card is stored without a 3-D Secure 2 authentication.

Your customer will be redirected to the URL configured in the request: cardsecure_url_confirm when the card storage is succeeded and cardsecure_url_cancel when the card storage fails.

Callback for a successful authentication:

{
  "type": "ADD_CARD",
  "event": "COMPLETED",
  "token": "92F0F59E-F4C7-11ED-BF8B-FA83F5CF2760",
  "request_id": "<uuid>"
}

You can also get this token using the /api/v2/requests/«uuid» service. Check this page for details.

Payment with Credit Card Token

Opposite to the “anonymous payment” service, the card data is already stored and you only need to pass the card token generated in the previous service.

As the customer already performed a 3-D Secure 2 authentication when the credit card was stored, the payment will be completed automatically.

You can pass a request_id in the payload to track this request. Check this page for details.

Request POST /prows/v2/payment
Query params none
Data params Operation
Returns Operation
Click here for an example
curl --location --request POST 'https://services.sandbox.meowallet.pt/prows/v2/payment' \
--header 'Authorization: WalletPT <merchant-wallet-API-Key>' \
--header 'Content-Type: application/json' \
--header 'Proxy-Authorization: ESB Token=<ESB-Token>' \
--data-raw '{
    "callback": "https://example.com",
    "cardsecure_url_confirm": "http://www.example.com",
    "cardsecure_url_cancel": "http://www.sapo.pt",
    "card": {
         "token": "D9448444-A651-11ED-AED8-7B991EF36F7B",
         "last4": "0010",
         "type": "visa",
         "valdate": "12/2025"
      },
      "method": "CC",
      "amount":1.5,
      "currency": "EUR",
      "ext_invoiceid":"pista",
      "ext_email":"sergio@telecom.pt",
      "ext_customerid":"Xavi"
}'
Response:
{
    "card": {
        "token": "D9448444-A651-11ED-AED8-7B991EF36F7B",
        "last4": "0010",
        "type": "visa",
        "valdate": "12/2025",
        "expired": false
    },
    "cardsecure_url_confirm": "http://www.example.com",
    "cardsecure_url_cancel": "http://www.sapo.pt",
    "currency": "EUR",
    "id": "b096521a-2c8a-450f-af15-f278fdc85103",
    "ipaddress": "10.134.167.217",
    "ext_invoiceid":"pista",
    "ext_email":"sergio@telecom.pt",
    "ext_customerid":"Xavi",
    "type": "PAYMENT",
    "channel": "WEBSITE",
    "modified_date": "2023-03-08T11:11:35+0000",
    "notes": "",
    "user_notes": "",
    "refundable": false,
    "fee": -0.9,
    "amount": 1.5,
    "amount_net": 0.6,
    "merchant": {
        "id": "600000000",
        "name": "testmerchant",
        "email": "testmerchant@telecom.pt"
    },
    "date": "2023-03-08T11:11:31+0000",
    "method": "CC",
    "status": "COMPLETED"
}


Get Credit Card

This service returns card data given a card token.

Request GET /prows/v2/creditcard/:token
Query params token
Data params none
Returns CreditCard
Click here for an example
curl --location --request GET 'https://services.sandbox.meowallet.pt/prows/v2/creditcard/D9448444-A651-11ED-AED8-7B991EF36F7B' \
--header 'Authorization: WalletPT <merchant-wallet-API-Key> \
--header 'Content-Type: application/json' \
--header 'Proxy-Authorization: ESB Token=<ESB-Token>'
Example response:
{
    "verification_status": "VERIFIED",
    "token": "D9448444-A651-11ED-AED8-7B991EF36F7B",
    "last4": "0010",
    "bin": "401881",
    "type": "visa",
    "name": "Test test",
    "valdate": "12/2025",
    "expired": false
}


Delete Credit Card

This service deletes a credit card given the token.

Request DELETE /prows/v2/creditcard/:token
Query params token
Data params none
Returns boolean
Click here for an example
curl --location --request DELETE 'https://services.sandbox.meowallet.pt/prows/v2/creditcard/D9448444-A651-11ED-AED8-7B991EF36F7B' \
--header 'Authorization: WalletPT <merchant-wallet-API-Key>' \
--header 'Content-Type: application/json' \
--header 'Proxy-Authorization: ESB Token=<ESB-Token>' \
Response: **true**

Structures

StoreCardRequest

Field Type In/Out Mandatory Description
newCard NewCard I N object with the plain card data (available only for PCI DSS merchants)
newCardSecure NewCardSecure I N object with the encrypted card data
cardsecure_url_confirm string I Y redirect to be used when the card is stored successfully
cardsecure_url_cancel string I Y redirect to be used when the card is not stored
request_id string I Y request id returned in the callback with the 3-D Secure 2 authentication

NewCard

Field Type In/Out Mandatory Description
address Address I N card owner address
number string I Y card number
name string I Y card owner name
vcode string I Y cvv
valdate string I Y card expiration date as MM/YYYY

NewCardSecure

Field Type In/Out Mandatory Description
address Address I N card owner address
number string I Y card number encrypted
name string I Y card owner name encrypted
vcode string I Y cvv encrypted
valdate string I Y card expiration date encrypted

Address

Field Type In/Out Mandatory Description
address string IO N street address including door number
city string IO Y city, e.g: Lisbon
country string IO Y ISO 3166-1-alpha-2
postalcode string I Y Postal code (ex. 1000-100)

CreditCard

Field Type In/Out Mandatory Description  
verification_status string O Y VERIFIED/UNVERIFIED  
bin string O Y Bank Identification Number  
expired boolean O Y card valid  
voided boolean O Y true if the credit card has been deleted  
last4 string IO Y last four digits of the card number  
token string IO Y GUID representing the card in MEO Wallet  
type string IO Y card brand  
valdate string IO Y card expiration date as MM/YYYY  

CardSecureResponse

Field Type In/Out Mandatory Description
cardsecure_url_redirect string O Y bank card issuer url

Operation

The table describes the mandatory and specific fields for the Prows 2 Credit Card API. For a full description of the available fields, check the Structures documentation.

Field Type In/Out Mandatory Description
amount float I Y payment amount
currency string I Y amount currency in ISO 4217
merchant Merchant O Y transaction recipient
callback string IO Y valid url to receive the callback
method string IO Y payment method - CC
card CreditCard IO N object with the card token details
newCard NewCard I N object with the plain card data
newCardSecure NewCardSecure I N object with the encrypted card data
cardsecure_url_confirm string IO Y redirect url to be used if payment completes
cardsecure_url_cancel string IO Y redirect url to be used if the payment fails

Merchant

Field Type In/Out Mandatory Description
id string O Y internal merchant id
email string O Y merchant email
name string O N merchant comercial name
apikey string I Y merchant API Key