Failure Notification
How to interpret the POST data parameters included in the callback notification e-mail triggered by the payment callback function.
Info
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 e-mail address you define in the payment administration tool
- callback.failures@spilgames
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:
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:
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:
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 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