Carrier Billing

REST API

Carrier Billing is a type of Online Bank Transfer.

Countries and Currencies

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

Transaction Types

For transaction type details look at Transaction Types.

Transaction Type Link to the Sample

debit

debit sample

refund-debit

debit for carrier-billing

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

Workflow
Using ReST API
CarrierBilling Workflow REST
  1. On the merchant site.

  2. Consumers select carrier billing.

  3. The merchant sends a payment request to Wirecard Payment Gateway.

  4. Wirecard Payment Gateway redirects consumers to provider’s page.

  5. Continue with point 4 of "Using Payment Page".

Using Payment Page
CarrierBilling Workflow PP
  1. On the Payment Page.

  2. Consumers select carrier billing.

  3. Wirecard Payment Gateway redirects consumers to provider’s page.

  4. Consumers select their mobile network provider.

    SelectProvider

    and confirm payment.

    Confirm Payment
  5. Consumers submit the payment.

  6. The provider processes the payment and sends a notification to Wirecard Payment Gateway.

  7. Wirecard Payment Gateway confirms the payment.

  8. Merchant redirects consumers to merchant’s confirmation page.

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

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

64

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.

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

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

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=&
Custom URL: