Wirecard Documentation

Carrier Billing

REST API

Please note that you can use the REST API documentation also for Wirecard Payment Page v1 integration.

Carrier Billing is a type of Online Bank Transfer.

Countries	EUR Countries
Currencies	EUR

Communication Formats

This table illustrates how carrier billing notifications are encoded and which formats and methods can be used for requests and responses.

Requests/Responses	Format	XML
Methods	POST, GET
IPN Encodement	Base64, JSON

Requests/Responses

Format

XML

Methods

POST, GET

IPN Encodement

Base64, JSON

Transaction Types

For transaction type details look at Transaction Types.

Transaction Type	Link to the Sample
debit	debit sample
refund-debit

Transaction Type

Link to the Sample

debit

debit sample

refund-debit

The payment method within the request must be carrier-billing, the transaction type debit. If the request is successful, the Forward-URL to the Landing-Page of the carrier-billing provider will be sent in the response. The notification allows a merchant to receive the final status of a payment as soon as Wirecard receives it from the carrier-billing provider. Usually, this status is received within seconds of the completion of the transaction, however, may take up to a few days depending on the respective mobile provider.

Once Wirecard has received a notification from the carrier-billing provider about the final status of the transaction, this status will be communicated to the merchant via the Notification URL that is configured in the merchant account or provided with the initial payment transaction request.

If no notification URL is provided with the request and also not configured in the merchant account, the notification will be sent via Email to the merchant in case the Email address has been configured. In case merchant has not received the notification, the status of the transaction can be requested by sending a Retrieve Transaction by Transaction ID or Retrieve Transaction by Request ID.

Test Credentials

URLs (Endpoints)	`https://api-test.wirecard.com/engine/rest/paymentmethods/`
Test Merchant Account ID (MAID)	8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7
Username	16390-testing
Password	3!3013=D3fD8X7
Secret Key	c5baf402-82cd-453d-9f5a-1b20ad44f982

URLs (Endpoints)

https://api-test.wirecard.com/engine/rest/paymentmethods/

Test Merchant Account ID (MAID)

8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key

c5baf402-82cd-453d-9f5a-1b20ad44f982

Additional Test Credentials on carrier billing’s Environment

Test Number	DE00, SK00

Test Number

DE00, SK00

Workflow

Using ReST API

On the merchant site.
Consumers select carrier billing.
The merchant sends a payment request to Wirecard Payment Gateway.
Wirecard Payment Gateway redirects consumers to provider’s page.
Continue with point 4 of "Using Payment Page".

Using Payment Page

On the Payment Page.
Consumers select carrier billing.
Wirecard Payment Gateway redirects consumers to provider’s page.
Consumers select their mobile network provider.

and confirm payment.
Consumers submit the payment.
The provider processes the payment and sends a notification to Wirecard Payment Gateway.
Wirecard Payment Gateway confirms the payment.
Merchant redirects consumers to merchant’s confirmation page.
The amount to be paid appears on the consumer’s monthly carrier invoice.

Fields

The following elements are either mandatory (M), optional (O) or conditional (C) in a transaction process.

Field Request Response Notification Datatype Size Description

Field	Request	Response	Notification	Datatype	Size	Description
transaction-type	M	M	M	Alphanumeric	30	This is the type for a transaction. For carrier-billing only `debit` is allowed in the initial request.
transaction-id	M	M	M	Alphanumeric	36	The Transaction ID is the unique identifier for a transaction. It is generated by Wirecard.
statuses.status@severity		M	M	Alphanumeric	20	This field gives information if a status is a warning, an error or an information.
statuses.status@description		M	M	Alphanumeric	256	This is the description to the status code of a transaction.
statuses.status@code		M	M	Alphanumeric	12	This is the code of the status of a transaction.
state		M	M	Alphanumeric	12	The payment transaction state. For carrier-billing can only be success, failed or in-progress.
requested-amount@currency	M	M	M	Alphanumeric	3	The ISO code of the payment currency. Currently only `EUR` is supported.
requested-amount	M	M	M	Numeric	18.3	This is the amount of the transaction. The amount of the decimal place is dependent of the currency. The maximum amount is highly dependent on the country and mobile network operator. Currently the maximal allowed amount is 30 EUR.
request-id	M	M	M	Alphanumeric	150	This is the identification number of the request. It has to be unique for each request.
payment-methods.payment-method-name@url		M		Alphanumeric	256	The forward URL to the carrier-billing provider checkout page. The end-consumer must be redirected to this URL in order to be able to complete the payment.
payment-methods.payment-method-name@name	M			Alphanumeric	15	This is the name of the payment method that that is chosen from the end-consumer. Currently only `carrier-billing` is supported.
parent-transaction-id	O	O		Alphanumeric	36	Transaction ID of the first transaction in the series.
order-detail	M	M		Alphanumeric	20	Additional description of the provided product or service.
notifications.notification@url	O	O		Alphanumeric	256	The URL to be used for the Instant Payment Notification. It overwrites the notification URL that is set up in the merchant configuration.
merchant-account-id	M	M	M	Alphanumeric	36	Unique identifier for a merchant account.
locale			M	Alphanumeric	6	ISO code of the language. Can be sent in the format `<language>` or in the format `<language_country>`.
instrument-country	O			Alphanumeric	2	The instrument country contains the information where the end-consumer belongs to.
descriptor	O			Alphanumeric	40	Description of the provided product or service. It will appear on the checkout web page and SMS texts and may also appear on the end-customers billing invoice from the mobile operator depending on the country and operator.
consumer-id	M			Alphanumeric	50	An id of the end-consumer in the merchant’s application e.g. account name, gamer alias, login username.
completion-time-stamp		M	M	Datetime		The completion timestamp of the transaction processing.
account-holder.phone	M	M		Alphanumeric	30	The phone number of the end-customer (MSISDN) intended to be used for payment
account-holder.address.country	M	M	M	Alphanumeric	3	The ISO code of the country used for the mobile payment. It influences the language of the checkout page and usage of the mobile operators. Currently only `DE` is supported.
account-holder.address.city	M	M		Alphanumeric	256	The city of residence of the account holder.
account-holder.address.street1	M	M		Alphanumeric	256	The street name of residence of the account holder.
account-holder.first-name	M	M		Alphanumeric	256	The first name of the account holder.
account-holder.last-name	M	M		Alphanumeric	256	The last name of the account holder.
account-holder.email	M	M	M	Alphanumeric	256	The e-mail address of the account holder.

transaction-type

Alphanumeric

This is the type for a transaction. For carrier-billing only debit is allowed in the initial request.

transaction-id

Alphanumeric

The Transaction ID is the unique identifier for a transaction. It is generated by Wirecard.

statuses.status@severity

Alphanumeric

This field gives information if a status is a warning, an error or an information.

statuses.status@description

Alphanumeric

256

This is the description to the status code of a transaction.

statuses.status@code

Alphanumeric

This is the code of the status of a transaction.

state

Alphanumeric

The payment transaction state. For carrier-billing can only be success, failed or in-progress.

requested-amount@currency

Alphanumeric

The ISO code of the payment currency. Currently only EUR is supported.

requested-amount

Numeric

18.3

This is the amount of the transaction. The amount of the decimal place is dependent of the currency. The maximum amount is highly dependent on the country and mobile network operator. Currently the maximal allowed amount is 30 EUR.

request-id

Alphanumeric

150

This is the identification number of the request. It has to be unique for each request.

payment-methods.payment-method-name@url

Alphanumeric

256

The forward URL to the carrier-billing provider checkout page. The end-consumer must be redirected to this URL in order to be able to complete the payment.

payment-methods.payment-method-name@name

Alphanumeric

This is the name of the payment method that that is chosen from the end-consumer. Currently only carrier-billing is supported.

parent-transaction-id

Alphanumeric

Transaction ID of the first transaction in the series.

order-detail

Alphanumeric

Additional description of the provided product or service.

notifications.notification@url

Alphanumeric

256

The URL to be used for the Instant Payment Notification. It overwrites the notification URL that is set up in the merchant configuration.

merchant-account-id

Alphanumeric

Unique identifier for a merchant account.

locale

Alphanumeric

ISO code of the language. Can be sent in the format <language> or in the format <language_country>.

instrument-country

Alphanumeric

The instrument country contains the information where the end-consumer belongs to.

descriptor

Alphanumeric

Description of the provided product or service. It will appear on the checkout web page and SMS texts and may also appear on the end-customers billing invoice from the mobile operator depending on the country and operator.

consumer-id

Alphanumeric

An id of the end-consumer in the merchant’s application e.g. account name, gamer alias, login username.

completion-time-stamp

Datetime

The completion timestamp of the transaction processing.

account-holder.phone

Alphanumeric

The phone number of the end-customer (MSISDN) intended to be used for payment

account-holder.address.country

Alphanumeric

The ISO code of the country used for the mobile payment. It influences the language of the checkout page and usage of the mobile operators. Currently only DE is supported.

account-holder.address.city

Alphanumeric

256

The city of residence of the account holder.

account-holder.address.street1

Alphanumeric

256

The street name of residence of the account holder.

account-holder.first-name

Alphanumeric

256

The first name of the account holder.

account-holder.last-name

Alphanumeric

256

The last name of the account holder.

account-holder.email

Alphanumeric

256

The e-mail address of the account holder.

Features

Merchant Country Code Security

Depending on the merchant account ID, merchants will only be able to accept payments from the setup country. This means one country for one merchant account ID.

Samples

Carrier Billing: Debit JSON

Request Details
API Endpoint
Method	POST
URI	`https://api-test.wirecard.com/engine/rest/paymentmethods/`
Headers
Content-Type	`application/json`
Accept	`application/json`

{
  "payment": {
    "merchant-account-id": {
      "value": "8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7"
    },
    "requested-amount": {
      "currency": "EUR",
      "value": 10
    },
    "request-id": "{{$guid}}",
    "transaction-type": "debit",
    "payment-methods": {
      "payment-method": [
        {
          "name": "carrier-billing"
        }
      ]
    },
    "account-holder": {
      "email": "john.doe@example.com",
      "first-name": "John",
      "last-name": "Doe",
      "phone": "SK00",
      "address": {
        "street1": "Test Street 123",
        "city": "Test City",
        "country": "SK"
      }
    },
    "consumer-id": "Test Consumer",
    "order-detail": "Test Order",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "notifications": {
      "notification": [
        {
          "url": "http://requestbin.fullcontact.com/uom1iruo"
        }
      ],
      "format": "application/json"
    }
  }
}

Response Details
Headers
Content-Type	`application/json`
Status
Code	`201.0000`
Severity	`information`
Description	`The resource was successfully created.`

{
  "payment": {
    "statuses": {
      "status": [
        {
          "code": "201.0000",
          "description": "The resource was successfully created.",
          "severity": "information"
        }
      ]
    },
    "notifications": {
      "notification": [
        {
          "url": "http://requestbin.fullcontact.com/uom1iruo"
        }
      ],
      "format": "application/json"
    },
    "merchant-account-id": {
      "value": "8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7"
    },
    "transaction-id": "5de8661b-959d-49ba-aca0-d884df0c6d4b",
    "request-id": "3e667077-81fe-4415-b8c5-e3d471d66ccd",
    "transaction-type": "debit",
    "transaction-state": "success",
    "completion-time-stamp": 1573460983000,
    "requested-amount": {
      "value": 10,
      "currency": "EUR"
    },
    "account-holder": {
      "email": "john.doe@example.com",
      "phone": "SK00",
      "address": {
        "street1": "Test Street 123",
        "city": "Test City",
        "country": "SK"
      },
      "first-name": "John",
      "last-name": "Doe"
    },
    "order-detail": "Test Order",
    "payment-methods": {
      "payment-method": [
        {
          "url": "https://buy.boku.com/checkoutidentify/5v6oz1myvszdhcwp5jxz5plz/buy.js",
          "name": "carrier-billing"
        }
      ]
    },
    "consumer-id": "Test Consumer",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success"
  }
}

NVP

Request Details
API Endpoint
Method	POST
URI	`https://api-test.wirecard.com/engine/rest/paymentmethods/`
Headers
Content-Type	`application/x-www-form-urlencoded;charset=UTF-8`
Accept	`text/plain`

merchant_account_id=8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7&requested_amount_currency=EUR&requested_amount=10&request_id={{$guid}}&transaction_type=debit&payment_method=carrier-billing&email=john.doe%40example.com&first_name=John&last_name=Doe&phone=SK00&street1=Test%20Street%20123&city=Test%20City&country=SK&consumer_id=Test%20Consumer&order_detail=Test%20Order&cancel_redirect_url=https%3A%2F%2Fdemoshop-test.wirecard.com%2Fdemoshop%2F%23%2Fcancel&success_redirect_url=https%3A%2F%2Fdemoshop-test.wirecard.com%2Fdemoshop%2F%23%2Fsuccess&fail_redirect_url=https%3A%2F%2Fdemoshop-test.wirecard.com%2Fdemoshop%2F%23%2Ferror&notification_url=http%3A%2F%2Frequestbin.fullcontact.com%2Fuom1iruo

Key	Value
merchant_account_id	8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7
requested_amount_currency	EUR
requested_amount	10
request_id	{{$guid}}
transaction_type	debit
payment_method	carrier-billing
email	john.doe@example.com
first_name	John
last_name	Doe
phone	SK00
street1	Test Street 123
city	Test City
country	SK
consumer_id	Test Consumer
order_detail	Test Order
cancel_redirect_url	https://demoshop-test.wirecard.com/demoshop/#/cancel
success_redirect_url	https://demoshop-test.wirecard.com/demoshop/#/success
fail_redirect_url	https://demoshop-test.wirecard.com/demoshop/#/error
notification_url	http://requestbin.fullcontact.com/uom1iruo

Key

Value

merchant_account_id

8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7

requested_amount_currency

EUR

requested_amount

request_id

transaction_type

debit

payment_method

carrier-billing

john.doe@example.com

first_name

John

last_name

Doe

phone

SK00

street1

Test Street 123

city

Test City

country

consumer_id

Test Consumer

order_detail

Test Order

cancel_redirect_url

https://demoshop-test.wirecard.com/demoshop/#/cancel

success_redirect_url

https://demoshop-test.wirecard.com/demoshop/#/success

fail_redirect_url

https://demoshop-test.wirecard.com/demoshop/#/error

notification_url

http://requestbin.fullcontact.com/uom1iruo

Response Details
Headers
Content-Type	`application/x-www-form-urlencoded;charset=UTF-8`
Status
Code	`201.0000`
Severity	`information`
Description	`The resource was successfully created.`

country=SK&notification_url_1=http%3A%2F%2Frequestbin.fullcontact.com%2Fuom1iruo&city=Test+City&order_detail=Test+Order&payment_method_url=https%3A%2F%2Fbuy.boku.com%2Fcheckoutidentify%2F5v6pqf4a91di5r7jb8luiv8z%2Fbuy.js&requested_amount=10&completion_time_stamp=20191111083029&consumer_id=Test+Consumer&merchant_account_id=8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7&fail_redirect_url=https%3A%2F%2Fdemoshop-test.wirecard.com%2Fdemoshop%2F%23%2Ferror&street1=Test+Street+123&first_name=John&email=john.doe%40example.com&payment_method=carrier-billing&transaction_id=38aaca3d-3951-4dd5-9345-449f97762fc5&status_severity_1=information&last_name=Doe&transaction_type=debit&status_code_1=201.0000&status_description_1=The+resource+was+successfully+created.&phone=SK00&cancel_redirect_url=https%3A%2F%2Fdemoshop-test.wirecard.com%2Fdemoshop%2F%23%2Fcancel&success_redirect_url=https%3A%2F%2Fdemoshop-test.wirecard.com%2Fdemoshop%2F%23%2Fsuccess&transaction_state=success&requested_amount_currency=EUR&request_id=de6406bf-e901-4ac8-80c5-7e56f82e05a2

Key	Value
country	SK
notification_url_1	http://requestbin.fullcontact.com/uom1iruo
city	Test City
order_detail	Test Order
payment_method_url	https://buy.boku.com/checkoutidentify/5v6pqf4a91di5r7jb8luiv8z/buy.js
requested_amount	10
completion_time_stamp	20191111083029
consumer_id	Test Consumer
merchant_account_id	8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7
fail_redirect_url	https://demoshop-test.wirecard.com/demoshop/#/error
street1	Test Street 123
first_name	John
email	john.doe@example.com
payment_method	carrier-billing
transaction_id	38aaca3d-3951-4dd5-9345-449f97762fc5
status_severity_1	information
last_name	Doe
transaction_type	debit
status_code_1	201.0000
status_description_1	The resource was successfully created.
phone	SK00
cancel_redirect_url	https://demoshop-test.wirecard.com/demoshop/#/cancel
success_redirect_url	https://demoshop-test.wirecard.com/demoshop/#/success
transaction_state	success
requested_amount_currency	EUR
request_id	de6406bf-e901-4ac8-80c5-7e56f82e05a2

Key

Value

country

notification_url_1

http://requestbin.fullcontact.com/uom1iruo

city

Test City

order_detail

Test Order

payment_method_url

https://buy.boku.com/checkoutidentify/5v6pqf4a91di5r7jb8luiv8z/buy.js

requested_amount

completion_time_stamp

20191111083029

consumer_id

Test Consumer

merchant_account_id

8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7

fail_redirect_url

https://demoshop-test.wirecard.com/demoshop/#/error

street1

Test Street 123

first_name

John

john.doe@example.com

payment_method

carrier-billing

transaction_id

38aaca3d-3951-4dd5-9345-449f97762fc5

status_severity_1

information

last_name

Doe

transaction_type

debit

status_code_1

201.0000

status_description_1

The resource was successfully created.

phone

SK00

cancel_redirect_url

https://demoshop-test.wirecard.com/demoshop/#/cancel

success_redirect_url

https://demoshop-test.wirecard.com/demoshop/#/success

transaction_state

success

requested_amount_currency

EUR

request_id

de6406bf-e901-4ac8-80c5-7e56f82e05a2

XML

Request Details
API Endpoint
Method	POST
URI	`https://api-test.wirecard.com/engine/rest/paymentmethods/`
Headers
Content-Type	`application/xml`
Accept	`application/xml`

<?xml version="1.0" encoding="utf-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7</merchant-account-id>
    <requested-amount currency="EUR">10</requested-amount>
    <request-id>{{$guid}}</request-id>
    <transaction-type>debit</transaction-type>
    <payment-methods>
        <payment-method name="carrier-billing" />
    </payment-methods>
    <account-holder>
        <!-- either set mandatoty element: payment/wallet/account-id or payment/account-holder/email -->
        <email>john.doe@example.com</email>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <phone>SK00</phone>
        <address>
            <street1>Test Street 123</street1>
            <city>Test City</city>
            <country>SK</country>
        </address>
    </account-holder>
    <consumer-id>Test Consumer</consumer-id>
    <order-detail>Test Order</order-detail>
    <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
    <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
    <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
    <notifications>
            <notification url="http://requestbin.fullcontact.com/uom1iruo"/>
    </notifications>
</payment>

Response Details
Headers
Content-Type	`application/xml`
Status
Code	`201.0000`
Severity	`information`
Description	`The resource was successfully created.`

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <merchant-account-id>8b99e2dc-c8d0-43b8-9ebb-0a35fa808af7</merchant-account-id>
  <transaction-id>af048f9c-a808-402f-bb42-53cb9fa9977f</transaction-id>
  <request-id>eb0740d7-c329-4301-9ac3-cde4b16b62f0</request-id>
  <transaction-type>debit</transaction-type>
  <transaction-state>success</transaction-state>
  <completion-time-stamp>2019-11-11T08:31:15.000Z</completion-time-stamp>
  <statuses>
    <status code="201.0000" description="The resource was successfully created." severity="information"/>
  </statuses>
  <requested-amount currency="EUR">10</requested-amount>
  <account-holder>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <email>john.doe@example.com</email>
    <phone>SK00</phone>
    <address>
      <street1>Test Street 123</street1>
      <city>Test City</city>
      <country>SK</country>
    </address>
  </account-holder>
  <order-detail>Test Order</order-detail>
  <notifications>
    <notification url="http://requestbin.fullcontact.com/uom1iruo">
    </notification>
  </notifications>
  <payment-methods>
    <payment-method url="https://buy.boku.com/checkoutidentify/5v6pqbfttmh2y8xt8xzf5k4b/buy.js" name="carrier-billing"/>
  </payment-methods>
  <consumer-id>Test Consumer</consumer-id>
  <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
  <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
  <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
</payment>

Notification (Successful)

response_signature=2a715f3ac100ad38906d48c84717840c40f6a0990390c8be0273cb23104d7960&phone=SK00&transaction_type=debit&locale=&completion_time_stamp=20150709141336&status_code_1=201.0000&status_severity_1=information&transaction_state=success&transaction_id=ec87fe6b-2633-11e5-94a1-0050b65c678c&country=SK&merchant_account_id=d97a261d-dbee-4993-b323-2349d51b768b&ip_address=127.0.0.1&provider_transaction_reference_id=&request_id=5ebb92fc-b72d-478c-98ec-7aca869b1e4c&requested_amount=15.00&requested_amount_currency=EUR&status_description_1=boku%3AThe+resource+was+successfully+created.&provider_transaction_id_1=&authorization_code=&

Wirecard Documentation

Carrier Billing

REST API

Countries and Currencies

Communication Formats

Transaction Types

debit for carrier-billing

Test Credentials

Additional Test Credentials on carrier billing’s Environment

Workflow

Using ReST API

Using Payment Page

Fields

Features

Merchant Country Code Security

Samples