Failure Notification

In this section you become familiar with the following parts of the in-game payment integration procedure:

How to interpret the POST data parameters included in the callback notification e-mail triggered by the payment callback function.

Info

When a payment reaches a specific status, the payment callback returns POST data to the game or the application.Use this information to validate the payment operation.Reply to this callback by sending a standard 200 OK HTTP response:

  • Status line: 200, and
  • Message body: [OK] (include the square brackets as well).

Send this reply to every payment notification you receive through the callback, regardless the reported payment status.

When you reply to the callback URL with [OK], you stop receiving automated callback notifications for payment transactions.

If you do not send this reply, callback POST data for payment transactions remain in the payment queue for 7 days/one week; during this period, callback notifications are sent on an hourly basis.

Callback failure notifications are automated e-mails triggered by the payment callback. They are sent to the following recipients:

The POST data format is always plain text, regardless the Content-Type header field value.

E-mail subject

Callback notification e-mail subjects follow the pattern described in the table below.

In an actual e-mail subject, the <game name> placeholder is replaced with the game name the callback failure notification refers to.

Environment E-mail subject
Live [Payment Service LIVE] Callback failure: <game name>

URL

The URL section contains the payment callback URL you as a game developer set and configure in the payment administration tool.

Use it to validate payment data on your end.

HEADERS

The HEADERS section contains the HTTP headers you as a game developer define and send along with the response.

Typical HTTP headers that can be included in a callback notification are:

The Status header and the status code associated to it can provide information about possible issues, for example when a payment fails (status code:404) or when the partner’s server behaves unexpectedly (status code: 500).

BODY

The BODY section contains the callback message body. You as a game developer define it. It can be anything you want to include.

If you want to stop receiving automated callback notifications for a given payment transaction, you need to reply with [OK] (square brackets included) in the BODY section. In this way, the POST data associated to that payment transaction are removed from the payment queue, and notification e-mail sending is stopped.

POST parameters

The BODY section contains the POST data parameters.

The table below lists the supplied POST parameters and their corresponding values.

Name Type Included? Definition
transaction_id integer Yes The transaction ID.You receive the transaction ID value from Spil Games.Every time a new payment is initiated, a new transaction ID is issued.Use this parameter and the corresponding value to verify payments on your end.When you want to refer to a specific payment transaction, include the corresponding transaction ID value in your communication with the Spil Games support team assisting you.Example: 123
amount integer Yes The amount due, the total sum the user needs to pay to purchase the selected package.The value is in cents.Example: 800
paid_amount integer Yes The amount the user paid to purchase the selected package.The value is in cents.Example: 800
game_id integer Yes The game ID value, as sent by the game developer to Spil Games on their first request.Example: 203
site_id integer Yes The site ID value, as sent by the game developer to Spil Games on their first request.Example: 79
channel_id integer Yes The channel ID value, as sent by the game developer to Spil Games on their first request.Example:
package_id integer Yes The package ID value, as sent by the game developer to Spil Games on their first request.Example: 42
sku_type string Yes The SKU type/name, as sent by the game developer to Spil Games on their first request.Example: coins
sku_unit integer Yes The SKU measurement unit, as sent by the game developer to Spil Games on their first request.Example: 100
transaction_token string Yes Unique identifier for the payment selection screen instantiation.Every time the payment selection screen is triggered, a new transaction token is generated.This parameter returns the token ID value of the options object that you send as an argument when you make a showPaymentSelectionScreen call.Example: unique-alphanumeric-string-1234
custom_parameters key-value pairs Yes Extra custom parameters that you want to be returned in the callback.This parameter returns the params value of the options object that you send as an argument when you make a showPaymentSelectionScreen call. It can take up to 200 characters.If no custom parameters are defined in the showPaymentSelectionScreen call, thecustom_parameters returned with the callback are empty.
Example: key: value
status string Yes End status of the transaction.The allowed values are:

  • OPEN
  • PAID
  • FAILED
  • PARTIAL
  • IGNORE
  • REFUND
  • NOT_REFUNDABLE

For further details, see Payment end statuses.

In case of a partial payment, check the PARTIAL payment end status in Payment end statuses.

Example: PAID

user_id string Yes The user name value, as sent by the game developer to Spil Games on their first request.The user name string value is case-insensitive.This parameter returns the userId value of the options JSON object that you send as an argument when you make a showPaymentSelectionScreen call.The returned user name value always corresponds to the user name value given by the initial payment, which may be in a different upper-/lowercase sequence.Example: james_kirk
internal_sku_name string Yes Internal SKU name for a specific SKU.The returned value identifies the pricing package the user selected and purchased.This value is not exposed to end users.Example: gamecoins
created date Yes The creation date of the transaction, i.e. when the transaction was initiated.Date format: YYYY-MM-DD HH:MM:SSExample: 2013-06-30 19:00:05
lastmodified date Yes The date of the latest/most recent change or modification to the transaction information.Date format: YYYY-MM-DD HH:MM:SSExample: 2013-06-30 19:01:12
paymentMethod string Yes The payment method the end-user selected to carry out and complete the transaction.Example: sms
provider string Yes The name or reference code of the payment provider service used to process the transaction.Example: paypal
currency string Yes The three-letter currency code reference, as used in the payment transaction.Example: EUR
hash string Yes Each call requires a handshake hash, generated using the SHA-256 algorithm.The hash value is calculated using the parameters included in this table, and you can find the secret key in the payment administration tool, on Menu>Account>Publisher Information. The secret is a:

  • 12 character long alphanumeric key;
  • It is unique.

For further details, see Hash verification.

Example: uniquealphanumericstring1234567890

is_subscription integer Yes This parameter flags whether a user has any active subscriptions.Allowed values are:

  • 1 (the user has at least one active subscription)
  • 0 (the user has no active subscriptions)

Default value: 0

Example: 0

multiplier decimal Yes This parameter allows you to check if a promotion multiplier applies to the transaction.Default value: 1Example: 1.5

Examples

Callback notification

Callback failure notification email example:


## URL

"http://www.gamedevserver.com/api/gameName/payments"

## HEADERS

HTTP/1.1 404 Not Found
Date: Tue, 23 Jul 2013 13:30:11 GMT
Server: Apache/2.2.24 (Unix) mod_ssl/2.2.24 OpenSSL/1.0.0-fips mod_auth_passthrough/2.1 mod_bwlimited/1.4 FrontPage/5.0.2.2635 PHP/5.3.24
X-Powered-By: PHP/5.3.24
Status: 404
Content-Length: 27
Content-Type: application/json

## BODY

"{"error":"Payment FAILED!"}"

## POST

Array</pre>
<pre class="prettyprint linenums lang-json">(
    [transaction_id] ⇒12345678 // Check this parameter to verify a transaction
    [amount] ⇒ 123
    [paid_amount] ⇒ 123
    [game_id] ⇒ 175
    [site_id] ⇒ 16
    [channel_id] ⇒ 1
    [package_id] ⇒ 12345
    [sku_type] ⇒ MegaCoins
    [sku_unit] ⇒ 100
    [transaction_token] ⇒ unique-alphanumeric-string-1234
    [custom_parameters] ⇒
    [status] ⇒ PAID
    [user_id] ⇒ phineasgauge1823
    [internal_sku_name] ⇒ gamecoins
    [created] ⇒ 2013-06-30 19:00:05
    [lastmodified] ⇒ 2013-06-30 19:01:12
    [paymentMethod] ⇒ sms
    [provider] ⇒ payment-provider-name
    [currency] ⇒ EUR
    [hash] ⇒ f15da616592a0eb
    [is_subscription] ⇒ 0
)
</pre>
<pre class="prettyprint linenums">This is an automated message. For further inquiries please contact payment@spilgames.com