Payments

The actual payment screens are hosted by the payment provider. This API starts a transaction and returns a token. That token is then used to start the transaction.

Transactions

This API enables you to begin a transaction so that a product can be purchased.

POST /transactions

Request

Parameters:
  • price (decimal) – Decimal amount of the purchase price. Example: 0.99.
  • currency (string) – ISO currency code for the purchase price. Examples: EUR, USD.
  • carrier (string) – Mobile carrier that the user is on when making a purchase. Example: TMOBILE.
  • region (string) – Numeric MCC (Mobile Country Code) of the region that the user is in when beginning the transaction. Example: 300.
  • success_url (url) – Fully qualified URL to where Zippy should redirect to after a successful payment. Example: https://marketplace.firefox.com/mozpay/provider/success.
  • error_url (url) – Fully qualified URL to where Zippy should redirect to after a payment error. Example: https://marketplace.firefox.com/mozpay/provider/error.
  • callback_success_url (url) – Fully qualified URL to where Zippy should issue a POST request if the payment is accepted with a signed_notice parameter (a “stringified” version of the parameters returned by the creation of the transaction). Example: https://marketplace.firefox.com/mozpay/provider/callback/success.
  • callback_error_url (url) – Fully qualified URL to where Zippy should issue a POST request if the payment is NOT accepted with a signed_notice parameter (a “stringified” version of the parameters sent for the creation of the transaction). Example: https://marketplace.firefox.com/mozpay/provider/callback/error.
  • ext_transaction_id (string) – An external transaction ID (string). This would be a merchant’s own transaction ID, such as Webpay transaction ID. This will be returned to the merchant in a payment notice for reconciliation.
  • pay_method (string) –

    Method of payment requested. Possible values:

    CARD
    Credit card.
    OPERATOR
    Mobile operator billing.
  • product_id (string) – Primary key of product about to be purchased.
  • product_image_url – An optional sanitized image URL to display the logo of the product. A default image will be displayed during the payment process if that field is not submitted.

For example:

{
  "price":"0.89",
  "currency":"EUR",
  "pay_method": "OPERATOR",
  "carrier": "TMOBILE",
  "region": 300,
  "product_id": 1,
  "success_url": "https://yoursite.org/success",
  "error_url": "https://yoursite.org/error",
  "callback_success_url": "https://yoursite.org/callback/success",
  "callback_error_url": "https://yoursite.org/callback/error",
  "product_image_url": "http://example.org/image.jpg",
  "resource_pk": "1",
  "resource_name": "transactions",
  "resource_uri": "/transactions/1"
}

Response

The created transaction is returned to you with a few extra fields.

Parameters:
  • status – The status of the transaction.
  • token – Unique token that can be used to address this transaction.

For example:

{
  "status": "started",
  "token": "f74b2b68ad5cce2c07b14e06ed67b76e56ab91196bac605...",
}

In case of an error:

{
  "code": "InvalidArgument",
  "message": {
    "product_id": "This field is required."
  }
}
Status Codes:
  • 201 – success.
  • 409 – conflict.

Carrier Authentication

This is a basic flow for how carrier authentication works.

_images/auth-flow.png

SMS Authentication

This shows a flow and screens where a payment provider discovers the user via SMS messages to the phone.

Example:

_images/sms-auth.png _images/sms-auth-confirm.png

Payment page

Carrier billing page

Example:

_images/carrier-billing.png

Credit card

Example:

_images/credit-card.png

Credit card or carrier billing

Currently when a user lands on the buy page, the user has to choose between using carrier billing or a credit card. This diagram outlines the choices.

_images/buy-flow.png