InPlayer API (2.0.0)

Download OpenAPI specification:Download

INTRODUCTION

Our Paywall platform enables you up to create a detailed subscription business, allowing you to build a consumer base and drive significant revenues. Our paywall supports recurring payments and billing, consumer acquisition, subscriber lifecycle management and gives you consumer retention CRM tools.

Once you have an InPlayer Merchant Account you can use our dashboard at https://dashboard.inplayer.com to publish, manage and sell premium content. However, you can always integrate with our APIs for full custom integration.

INPLAYER API

The InPlayer API has REST architecture. It has mostly resource-oriented URLs, and uses standard HTTP response codes to indicate API errors or success requests. Every InPlayer Core Resource has its own URL and each operation (GET, POST, PUT, and DELETE) has a specific meaning

All API requests should be made with Content-Type:application/x-www-form-urlencoded header.

JSON is returned by all API responses, no matter if they are success or errors.

DOCS TERMINOLOGY

In the section bellow you can find explanation about the terms that are used for the Core Resources in the InPlayer Platform. Be sure to read it before you start with custom integration.

Accounts and Account Types

Term Explanation
merchant The Merchants are those that has ownership of the premium content.
consumer The Consumers are those that can view or buy the premium content.
customer Consumer with at least one purchase.
uuid Unique identifier of the Merchant. You can find it in the InPlayer dashboard in the Account Details section as Account ID.

Items/Assets and Item Types

Term Explanation
items Items or sometimes referred as Assets are the digital assets that Merchants can protect and sell. Asset is an Item with applied pricing and access options.
item_type Is the type of the digital content that can be created in the InPlayer Platform. The only difference between the Item Types is the premium content type. Currently, only available options for Item Types are html_asset where you can store HTML code or any IFRAME code, and ooyala_asset where you can store digital asset content hosted in Ooyala.
content Content of one Item is the premium content that you can store and protect. Once the Consumer has access to the Item, he can view the content.
metadata Metadata is unlimited key-value store for describing Items.

Access Types

Term Explanation
access_type Types of access that can be used in the system.
period The time frame of the asset access that the consumer get after purchasing.

Access Fees

Term Explanation
access_fee Applied access_type and price to Item.

Items Packages

Term Explanation
package Collection of multiple Items. Packages are group of Items. You can set up Package Access Fee that will be additional pricing option for the Items that belong to a Package. Once the Consumer buys Package Access Fee he will have access to every Item that belongs to the Package.

API ENVIRONMENTS

To make the API as explorable as possible, we have 2 different environments for live or testing purposes. There is no switch for changing between modes, just use the different URLs of our API servers.

ERRORS

InPlayer uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with InPlayer's servers.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., asset access is not found), we return a 402 error code.

List of status codes

Status code Explanation
200 OK Everything worked as expected.
201 Created The resource has been created.
202 Accepted The request has been accepted for processing, but the processing has not been completed.
204 No Content The server has fulfilled the request but does not need to return an entity-body
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid access token provided.
402 Request Failed The parameters were valid but the request failed.
404 Not Found The requested resource doesn't exist.
409 Conflict The request conflicts with another request.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 Server Errors Something went wrong on InPlayer's end.

Authentication

bearerAuth

You can create a JSON Web Token (JWT) via the authenticate endpoint. Usage format: Bearer <JWT>

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

V1

All operations related to payments & subscriptions

Generate PayPal parameters

This API call requires Authorization header with Access Token for the Customer auth - Authorization: Bearer

With this call you will be able to generate all parameters needed for PayPal payments. Primarely the external PayPal link where you need to redirect the end user to complete the payment on PayPal site. In the API call you will need to send the origin where you want the end-user to be redirected back after the payment result from paypal.

Authorizations:
Request Body schema: application/x-www-form-urlencoded
access_fee
required
integer

Access fee id

payment_method
required
integer

Payment method id

origin
required
string

origin URL

voucher_code
string

Voucher code for discount

Responses

200

Paypal parameters

400

Invalid request

401

Unauthorized

422

Cannot create resource

post /external-payments
Staging Server
https://staging-v2.inplayer.com/external-payments
Production Server
https://services.inplayer.com/external-payments

Request samples

Copy
curl -X POST https://services.inplayer.com/external-payments \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{}

Cancels a PayPal subscription

Cancels the customer's PayPal subscription.

Authorizations:

Responses

201

Accepted for cancelling

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

get /external-payments/cancel/{subscription_id}
Staging Server
https://staging-v2.inplayer.com/external-payments/cancel/{subscription_id}
Production Server
https://services.inplayer.com/external-payments/cancel/{subscription_id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 201,
  • "subscription_id": "S-nvpjWSd5dZKt9mZZFC0iIu1s2-PP",
  • "message": "Submited for cancel"
}

Creates payment

⚠️ Warning - This method typically requires PCI SAQ D compliance

This API call requires Authorization header with Access Token for the Customer auth - Authorization: Bearer

In case of PayPal payments, since the proccess is external, there is different aproach to execute payment. Reffer to Get PayPal Params API calls when exploring this payment method.

Authorizations:
Request Body schema: application/x-www-form-urlencoded
number
required
string

The card number

card_name
required
string

The cardholder's name

cvv
required
integer

The card’s CVV number

exp_month
required
integer [ 1 .. 12 ]

The month that the customer’s card expires

exp_year
required
integer

The year that the customer’s card expires

access_fee
required
integer

Access fee id

payment_method
required
integer

Payment method id

voucher_code
string

Voucher code for discount

Responses

202

Submitted for payment

400

Process already running

401

Unauthorized

422

Cannot create resource

post /payments
Staging Server
https://staging-v2.inplayer.com/payments
Production Server
https://services.inplayer.com/payments

Request samples

Copy
curl -X POST  https://services.inplayer.com/payments \
    -H 'Authorization:Bearer <token>' \
    -d access_fee=3 \
    -d payment_method=1
    -d number=4556667461842391 \
    -d cvv=123 \
    -d exp_month=11 \
    -d exp_year=18 \
    -d card_name='John Doe' \
    -d voucher_code=F00B4R!@

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "Submitted for payment"
}

Get number of payments per asset per country

Returns the number of payments per asset and per country.

Authorizations:
query Parameters
startDate
string
Example: "2019-02-03T00:00:00.000Z"

The time and date set as the starting point of calculation

endDate
string
Example: "2019-02-03T23:59:59.000Z"

The time and date set as the ending point of calculation

itemId
integer
Example: 40383

The ID of the asset

countryIso
string
Example: "UK"

Two-letter alphabetic geocode that represents the user's country

Responses

200

An array of objects holding all the information regarding payments per asset and per country

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

get /payments/asset-country
Staging Server
https://staging-v2.inplayer.com/payments/asset-country
Production Server
https://services.inplayer.com/payments/asset-country

Request samples

Copy
curl https://services.inplayer.com/payments/asset-country \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "collection":
    [
    ]
}

Get Number of Payments per Asset

Returns the number of payments per asset.

Authorizations:
query Parameters
startDate
string
Example: "2019-02-03T00:00:00.000Z"

The time and date set as the starting point of calculation

endDate
string
Example: "2019-02-03T23:59:59.000Z"

The time and date set as the ending point of calculation

itemId
integer
Example: 40383

The ID of the asset

countryIso
string
Example: "UK"

Two-letter alphabetic geocode that represents the user's country

Responses

200

An array of objects holding all the payments per asset collected

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

get /payments/asset
Staging Server
https://staging-v2.inplayer.com/payments/asset
Production Server
https://services.inplayer.com/payments/asset

Response samples

application/json
Copy
Expand all Collapse all
{
  • "collection":
    [
    ]
}

Get merchant active payment method

Returns the current active payment method for the merchant.

path Parameters
merchantUUID
required
string <uuid>
Example: "528b1b80-5868-4abc-a9b6-4d3455d719c8"

The merchant's UUID

Responses

200

Payment method

401

Unauthorized

412

Precondition failed

get /payments/method/{merchant_uuid}
Staging Server
https://staging-v2.inplayer.com/payments/method/{merchant_uuid}
Production Server
https://services.inplayer.com/payments/method/{merchant_uuid}

Request samples

Copy
curl https://services.inplayer.com/payments/providers/{merchant_uuid}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 1,
  • "method_name": "Card",
  • "is_external": false,
  • "active": true,
  • "account_id": 2,
  • "provider_name": "Stripe"
}

Get merchant payment methods

The first thing that is needed before executing payments is the preferred payment method that should be the end-user choice. You can fetch all possible payment methods for one Merchant with the following call. You can use the Payment Method ID from the response in the future payment or subscription action.

Authorizations:
query Parameters
merchantID
integer

The ID of the follower account if the operation is called by a master account

all
boolean

If set to true all methods active/inactive will be returnet, if not, just the active methods

Responses

200

Payment methods

400

Bad request

401

Unauthorized

get /payments/methods
Staging Server
https://staging-v2.inplayer.com/payments/methods
Production Server
https://services.inplayer.com/payments/methods

Request samples

Copy
curl https://services.inplayer.com/payments/methods \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    }
]

Get merchant payment providers

This will return all of the Merchant's available and enabled payment providers.

Authorizations:

Responses

200

Payment providers

401

Unauthorized

get /payments/providers
Staging Server
https://staging-v2.inplayer.com/payments/providers
Production Server
https://services.inplayer.com/payments/providers

Request samples

Copy
curl https://services.inplayer.com/payments/providers \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "payment_methods":
    {
    },
  • "bank_statement": "Your Bank Statement",
  • "stripe_connect": false
}

Create a Bank Statement descriptor

Create a Bank Statement descritor, that will be displayed to the merchant's customers, when they receive their card payment notifications from their issuer bank

Authorizations:
Request Body schema: application/x-www-form-urlencoded
bank_statement
required
string

Bank Statement

Responses

200

Created Bank Statement

404

Not Found

post /payments/providers/bank-statement
Staging Server
https://staging-v2.inplayer.com/payments/providers/bank-statement
Production Server
https://services.inplayer.com/payments/providers/bank-statement

Request samples

Copy
curl -X POST https://services.inplayer.com/payments/providers/bank-statement \
    -H 'Authorization:Bearer <token>'
    -d bank_statement='Bank Statement'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200,
  • "message": "The bank statement was successfully set."
}

Delete a Bank Statement descriptor

Delete the merchant's custom payment bank descriptor (reverts to using the default InPlayer descriptor)

Authorizations:

Responses

200

Deleted Bank Statement

400

Invalid request

404

Not Found

delete /payments/providers/bank-statement
Staging Server
https://staging-v2.inplayer.com/payments/providers/bank-statement
Production Server
https://services.inplayer.com/payments/providers/bank-statement

Request samples

Copy
curl -X DELETE https://services.inplayer.com/payments/providers/bank-statement \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200,
  • "message": "The bank statement was successfully removed. Reverted to using the default InPlayer bank statement for further payments."
}

Get Revenue per Asset per Country

Returns revenue per asset and per country

Authorizations:
query Parameters
startDate
string
Example: "2019-02-03T00:00:00.000Z"

The time and date set as the starting point of calculation

endDate
string
Example: "2019-02-03T23:59:59.000Z"

The time and date set as the ending point of calculation

itemId
integer
Example: 40383

The ID of the asset

countryIso
string
Example: "UK"

Two-letter alphabetic geocode that represents the user's country

Responses

200

An array of object holding collected all the information about revenue per asset and per country

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

get /payments/revenue/asset-country
Staging Server
https://staging-v2.inplayer.com/payments/revenue/asset-country
Production Server
https://services.inplayer.com/payments/revenue/asset-country

Request samples

Copy
curl https://services.inplayer.com/payments/revenue/asset-country \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "collection":
    [
    ]
}

Get Revenue per Asset

Returns revenue per asset.

Authorizations:
query Parameters
startDate
string
Example: "2019-02-03T00:00:00.000Z"

The time and date set as the starting point of calculation

endDate
string
Example: "2019-02-03T23:59:59.000Z"

The time and date set as the ending point of calculation

itemId
integer
Example: 40383

The ID of the asset

countryIso
string
Example: "UK"

Two-letter alphabetic geocode that represents the user's country

Responses

200

An array of object holding collected all the information about revenue per asset

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

get /payments/revenue/asset
Staging Server
https://staging-v2.inplayer.com/payments/revenue/asset
Production Server
https://services.inplayer.com/payments/revenue/asset

Request samples

Copy
curl https://services.inplayer.com/payments/revenue/asset \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "collection":
    [
    ]
}

Stripe Connect request

With this call a merchant can make a request to have the Stripe Connect option enabled for his account

Authorizations:

Responses

201

Request created

401

Unauthorized

409

Conflict

422

Precondition failed

post /payments/stripe-connect-request
Staging Server
https://staging-v2.inplayer.com/payments/stripe-connect-request
Production Server
https://services.inplayer.com/payments/stripe-connect-request

Request samples

Copy
curl -X POST https://services.inplayer.com/stripe-connect-request \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 201,
  • "message": "Your request has been accepted and will be processed soon"
}

Stripe Connect

With this the merchant's Stripe account is connected to the InPlayer Stripe connect application

Authorizations:

Responses

200

Request created

400

Bad Request

403

Forbidden

409

Conflict

422

Precondition failed

post /payments/stripe-connect
Staging Server
https://staging-v2.inplayer.com/payments/stripe-connect
Production Server
https://services.inplayer.com/payments/stripe-connect

Request samples

Copy
curl -X POST https://services.inplayer.com/stripe-connect \
    -H 'Authorization:Bearer <token>'
    -d authorization_code=1234

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200
}

Get subscriptions

Get all the Customer/Merchant subscription records.

Authorizations:

Responses

200

Subscriptions collection

409

Conflict

get /subscriptions
Staging Server
https://staging-v2.inplayer.com/subscriptions
Production Server
https://services.inplayer.com/subscriptions

Request samples

Copy
curl https://services.inplayer.com/subscriptions \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "total": 1,
  • "page": 1,
  • "offset": 0,
  • "limit": 5,
  • "collection":
    [
    ]
}

Creates subscription

⚠️ Warning - This method typically requires PCI SAQ D compliance

Authorizations:
Request Body schema: application/x-www-form-urlencoded
number
required
string

The card number

card_name
required
string

The cardholder's name

cvv
required
integer

The card’s CVV number

exp_month
required
integer [ 1 .. 12 ]

The month that the customer’s card expires

exp_year
required
integer

The year that the customer’s card expires

access_fee
required
integer

Access fee id

payment_method
required
integer

Payment method id

voucher_code
string

Voucher code for discount

Responses

202

Submitted for payment

400

Process already running

401

Unauthorized

422

Cannot create resource

post /subscriptions
Staging Server
https://staging-v2.inplayer.com/subscriptions
Production Server
https://services.inplayer.com/subscriptions

Request samples

Copy
curl -X POST  https://services.inplayer.com/subscriptions \
    -H 'Authorization:Bearer <token>' \
    -d access_fee=3 \
    -d payment_method=1
    -d number=4556667461842391 \
    -d cvv=123 \
    -d exp_month=11 \
    -d exp_year=18 \
    -d card_name='John Doe' \
    -d voucher_code=F00B4R!@

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "Submitted for payment"
}

Cancels subscription

Cancels the customer's subscription

Authorizations:

Responses

202

Accepted for cancelling

400

Process already running

401

Unauthorized

422

Unprocessable Entity

get /subscriptions/cancel/{subscription_id}
Staging Server
https://staging-v2.inplayer.com/subscriptions/cancel/{subscription_id}
Production Server
https://services.inplayer.com/subscriptions/cancel/{subscription_id}

Request samples

Copy
curl https://services.inplayer.com/subscriptions/cancel/{subscription_id} \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 202,
  • "subscription": "S-nvpjWSd5dZKt9mZZFC0iIu1s2-ST",
  • "operation": "unsubscribe",
  • "description": null,
  • "status": "pending",
  • "timestamp": 1543238737
}

V2

Validates Amazon receipt

Validates an In App purchase from Amazon services

Authorizations:
Request Body schema: application/x-www-form-urlencoded
receipt
required
string

Amazon receipt string

amazon_user_id
string

Amazon user ID string

item_id
required
int64

The ID of the item

access_fee_id
required
int64

The ID of the access fee

Responses

200

OK

401

Unauthorized request

422

Missing input fields

post /v2/external-payments/amazon/validate
Staging Server
https://staging-v2.inplayer.com/v2/external-payments/amazon/validate
Production Server
https://services.inplayer.com/v2/external-payments/amazon/validate

Request samples

Copy
curl https://services.inplayer.com/v2/external-payments/amazon/validate \
  -H 'Authorization: <token>' \
  -d receipt="<receipt>" \
  -d amazon_user_id="<amazon_user_id>" \
  -d item_id=256 \
  -d access_fee_id=128

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200,
  • "message": "Submitted"
}

Validates Apple receipt

Validates an In App purchase from Apple services

Authorizations:
Request Body schema: application/x-www-form-urlencoded
receipt
required
string

Apple receipt string

item_id
required
int64

The ID of the item

access_fee_id
required
int64

The ID of the access fee

Responses

200

OK

401

Unauthorized request

422

Missing input fields

post /v2/external-payments/apple/validate
Staging Server
https://staging-v2.inplayer.com/v2/external-payments/apple/validate
Production Server
https://services.inplayer.com/v2/external-payments/apple/validate

Request samples

Copy
curl https://services.inplayer.com/v2/external-payments/apple/validate \
  -H 'Authorization: <token>' \
  -d receipt="<receipt>" \
  -d item_id=256 \
  -d access_fee_id=128

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200,
  • "message": "Submitted"
}

Cancels a Google Play subscription

Cancels the customer's Google Play subscription

Authorizations:

Responses

200

Accepted for cancelling

401

Unauthorized

422

Unprocessable Entity

post /v2/external-payments/google-play/cancel/{subscription_id}
Staging Server
https://staging-v2.inplayer.com/v2/external-payments/google-play/cancel/{subscription_id}
Production Server
https://services.inplayer.com/v2/external-payments/google-play/cancel/{subscription_id}

Request samples

Copy
curl https://services.inplayer.com/external-payments/google-play/cancel/{subscription_id} \
    -H 'Authorization:Bearer <token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200,
  • "message": "Submited"
}

Validates Google Play Receipt

Validates an In App purchase from Google Play store services

Authorizations:
Request Body schema: application/x-www-form-urlencoded
receipt
required
string

The Purchase object from Google Play response after a successful purchase

item_id
required
int64

The ID of the item

access_fee_id
required
int64

The ID of the access fee

Responses

200

OK

401

Unauthorized request

422

Missing input fields

post /v2/external-payments/google-play/validate
Staging Server
https://staging-v2.inplayer.com/v2/external-payments/google-play/validate
Production Server
https://services.inplayer.com/v2/external-payments/google-play/validate

Request samples

Copy
curl https://services.inplayer.com/v2/external-payments/google-play/validate \
  -H 'Authorization: <token>' \
  -d receipt="<receipt>" \
  -d item_id=2 \
  -d access_fee_id=23

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200,
  • "message": "Submitted"
}

Validates Roku receipt

Validates an In App purchase from Roku services

Authorizations:
Request Body schema: application/x-www-form-urlencoded
receipt
required
string

Roku receipt string

item_id
required
int64

The ID of the item

access_fee_id
required
int64

The ID of the access fee

Responses

200

OK

401

Unauthorized request

422

Missing input fields

post /v2/external-payments/roku/validate
Staging Server
https://staging-v2.inplayer.com/v2/external-payments/roku/validate
Production Server
https://services.inplayer.com/v2/external-payments/roku/validate

Request samples

Copy
curl https://services.inplayer.com/v2/external-payments/roku/validate \
  -H 'Authorization: <token>' \
  -d receipt="<receipt>" \
  -d item_id=256 \
  -d access_fee_id=128

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200,
  • "message": "Submitted"
}

Create charge

⚠️ Warning - This method typically requires PCI SAQ D compliance

Authorizations:
Request Body schema: application/x-www-form-urlencoded
access_fee_id
required
int

The ID of the Access Fee

item_id
required
int

Item id

voucher_code
string

The voucher code

payment_method
required
string

Payment Method

Responses

200

OK

401

Unauthorized

409

Conflict

422

Unprocessable entity

post /v2/payments
Staging Server
https://staging-v2.inplayer.com/v2/payments
Production Server
https://services.inplayer.com/v2/payments

Request samples

Copy
curl -X POST https://services.inplayer.com/v2/payments \
  -H 'authorization: Bearer <token>' \
      -d access_fee_id=16 \
      -d item_id=12 \
      -d voucher_code=CODE01 \
      -d payment_method=direct debit

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 200,
  • "message": "Submitted for payment"
}

Get default card

Returns the default credit card per currency used for subscription rebills.

Authorizations:

Responses

200

Default Card details per currency

401

Unauthorized

404

No Credit Card information found, please try again.

422

Unprocessable entity

get /v2/payments/cards/default
Staging Server
https://staging-v2.inplayer.com/v2/payments/cards/default
Production Server
https://services.inplayer.com/v2/payments/cards/default

Request samples

Copy
curl -X GET https://services.inplayer.com/v2/payments/cards/default \
  -H 'authorization: Bearer <token>' \

Response samples

application/json
Copy
Expand all Collapse all
{
  • "cards":
    {
    }
}

Set default card per currency

Sets card per currency as default card that is to be used for further subscription rebills.

Request Body schema: application/x-www-form-urlencoded
number
required
string

The card number

card_name
required
string

The cardholder's name

cvv
required
integer

The card’s CVV number

exp_month
required
integer [ 1 .. 12 ]

The month that the customer’s card expires

exp_year
required