Payments

All payments endpoints have path prefix /payments-service.

Example of main payments doc

{
  "_id": "shping_payments_plans",
  "currency": "aud",
  "list": [
    {
      "id": "basic",
      "name": "BASIC",
      "cost": 0,
      "hidden": false,
      "commitment_period": 0,
      "description": "Basic plan",
      "modules": [],
      "coin_rate": 0,
      "upgrade_description": "You are currently on the Basic plan and have limited access to product analytics and promotional opportunities. Upgrade now!",
      "description_list": [
        {
          "label": "GTIN",
          "value": "Unlimited"
        },
        {
          "label": "Product catalogue",
          "value": true
        },
        {
          "label": "Ingredients and Raw Materials",
          "value": true
        },
        {
          "label": "Availability Map",
          "value": false
        },
        {
          "label": "Engagement and Consumer Analytics",
          "value": false
        },
        {
          "label": "Reviews",
          "value": false
        },
        {
          "label": "Shoutouts",
          "value": false
        },
        {
          "label": "Shping bot",
          "value": false
        },
        {
          "label": "Rewards",
          "value": false
        },
        {
          "label": "Advanced Engagement (ToDo cards)",
          "value": false
        }
      ]
    },
    {
      "id": "light",
      "cost": 195,
      "name": "LIGHT",
      "hidden": false,
      "coin_rate": 0.1,
      "upgrade_description": "You are currently on the Light plan and have limited access to product analytics and promotional opportunities. Upgrade now!",
      "description": "Lite plan",
      "commitment_period": 52,
      "modules": [
        "product360",
        "reviews"
      ],
      "description_list": [
        {
          "label": "GTIN",
          "value": "1-20"
        },
        {
          "label": "Product catalogue",
          "value": true
        },
        {
          "label": "Ingredients and Raw Materials",
          "value": true
        },
        {
          "label": "Availability Map",
          "value": true
        },
        {
          "label": "Engagement and Consumer Analytics",
          "value": true
        },
        {
          "label": "Reviews",
          "value": true
        },
        {
          "label": "Shoutouts",
          "value": false
        },
        {
          "label": "Shping bot",
          "value": false
        },
        {
          "label": "Rewards",
          "value": false
        },
        {
          "label": "Advanced Engagement (ToDo cards)",
          "value": false
        }
      ]
    },
    {
      "id": "pro",
      "cost": 395,
      "name": "PRO",
      "description": "Standart plan",
      "coin_rate": 0.2,
      "hidden": false,
      "commitment_period": 52,
      "upgrade_description": "You are currently on the Pro plan and have limited access to product analytics and promotional opportunities. Upgrade now!",
      "modules": [
        "product360",
        "reviews",
        "rewards"
      ],
      "description_list": [
        {
          "label": "GTIN",
          "value": "21-500"
        },
        {
          "label": "Product catalogue",
          "value": true
        },
        {
          "label": "Ingredients and Raw Materials",
          "value": true
        },
        {
          "label": "Availability Map",
          "value": true
        },
        {
          "label": "Engagement and Consumer Analytics",
          "value": true
        },
        {
          "label": "Reviews",
          "value": true
        },
        {
          "label": "Shoutouts",
          "value": true
        },
        {
          "label": "Shping bot",
          "value": true
        },
        {
          "label": "Rewards",
          "value": true
        },
        {
          "label": "Advanced Engagement (ToDo cards)",
          "value": true
        }
      ]
    },
    {
      "id": "pro-corp",
      "name": "PRO-CORP",
      "description": "Pro plan",
      "upgrade_description": "C​orp-Pro is our top level, you already have access to all Shping's great features​!",
      "cost": 495,
      "hidden": false,
      "coin_rate": 0.3,
      "commitment_period": 52,
      "modules": [
        "product360",
        "reviews",
        "livechat",
        "rewards"
      ],
      "description_list": [
        {
          "label": "GTIN",
          "value": "501-999"
        },
        {
          "label": "Product catalogue",
          "value": true
        },
        {
          "label": "Ingredients and Raw Materials",
          "value": true
        },
        {
          "label": "Availability Map",
          "value": true
        },
        {
          "label": "Engagement and Consumer Analytics",
          "value": true
        },
        {
          "label": "Reviews",
          "value": true
        },
        {
          "label": "Shoutouts",
          "value": true
        },
        {
          "label": "Shping bot",
          "value": true
        },
        {
          "label": "Rewards",
          "value": true
        },
        {
          "label": "Advanced Engagement (ToDo cards)",
          "value": true
        }
      ]
    }
  ],
  "type": "system_doc"
}

User card

Set the by token

PUT /payments-service/user/card/:token
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
TODO

Delete the card

DELETE /payments-service/user/card
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket

Read actual billing plans

Read this plans

GET /payments-service/billing_plans
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
  "currency": "aud",
  "id": "shping_payments_plans",
  "list": [
    {
      "commitment_period": 0,
      "cost": 0,
      "description": "Basic plan",
      "description_list": {
        "Advanced Engagement (ToDo cards)": false,
        "Availability Map": false,
        "Engagement and Consumer Analytics": false,
        "GTIN": "Unlimited",
        "Ingredients and Raw Materials": true,
        "Product catalogue": true,
        "Reviews": false,
        "Rewards": false,
        "Shoutouts": false,
        "Shping bot": false
      },
      "hidden": false,
      "id": "basic",
      "modules": [],
      "name": "BASIC",
      "coin_rate": 0
    },
    {
      "commitment_period": 52,
      "cost": 195,
      "description": "Lite plan",
      "description_list": {
        "Advanced Engagement (ToDo cards)": false,
        "Availability Map": true,
        "Engagement and Consumer Analytics": true,
        "GTIN": "1-20",
        "Ingredients and Raw Materials": true,
        "Product catalogue": true,
        "Reviews": true,
        "Rewards": false,
        "Shoutouts": false,
        "Shping bot": false
      },
      "hidden": false,
      "id": "light",
      "modules": [
        "product360",
        "reviews"
      ],
      "name": "LIGHT",
      "coin_rate": 0.1
    },
    {
      "commitment_period": 52,
      "cost": 395,
      "description": "Standart plan",
      "description_list": {
        "Advanced Engagement (ToDo cards)": true,
        "Availability Map": true,
        "Engagement and Consumer Analytics": true,
        "GTIN": "21-500",
        "Ingredients and Raw Materials": true,
        "Product catalogue": true,
        "Reviews": true,
        "Rewards": true,
        "Shoutouts": true,
        "Shping bot": true
      },
      "hidden": false,
      "id": "pro",
      "modules": [
        "product360",
        "reviews",
        "rewards"
      ],
      "name": "PRO",
      "coin_rate": 0.2
    },
    {
      "commitment_period": 52,
      "cost": 495,
      "description": "Pro plan",
      "description_list": {
        "Advanced Engagement (ToDo cards)": true,
        "Availability Map": true,
        "Engagement and Consumer Analytics": true,
        "GTIN": "501-999",
        "Ingredients and Raw Materials": true,
        "Product catalogue": true,
        "Reviews": true,
        "Rewards": true,
        "Shoutouts": true,
        "Shping bot": true
      },
      "hidden": false,
      "id": "pro-corp",
      "modules": [
        "product360",
        "reviews",
        "livechat",
        "rewards"
      ],
      "name": "PRO-CORP",
      "coin_rate": 0.3
    }
  ]
}

Participant Billing Plan

Read Current Billing Plan

Retrieves active billing plan of current participant. Returns JSON with plan and payment card info.

GET /payments-service/participants/current/billing_plan
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Activated plan. Example Response
{
    "card": {
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "brand": "Visa",
        "exp_month": 11,
        "exp_year": 2022,
        "id": "card_1CrRhbEFVOePY2EFnZr18Tmf",
        "last4": "4242",
        "name": "Ivan Vasilev"
    },
    "contract": {
        "from": "2017-07-11",
        "terminate_available": true,
        "terminated": false,
        "to": "2018-08-24"
    },
    "paid_from": "2018-07-24",
    "paid_to": "2018-08-24",
    "plan": "light",
    "trial": {
        "status": false
    },
    "updated_at": "2017-07-11T14:41:30Z",
    "user_email": [
        "billing_test5@mailinator.com"
    ]
}
Trial plan. Example Response
{
    "card": null,
    "contract": {
        "terminate_available": true,
        "terminated": false
    },
    "paid_from": null,
    "paid_to": null,
    "plan": "complete",
    "trial": {
        "form": "2018-06-24T14:33:40Z",
        "status": true,
        "to": "2018-07-24T14:33:40Z"
    },
    "updated_at": "2018-07-24T15:36:23Z",
    "user_email": [
        "billing_test5@mailinator.com"
    ]
}

Change Billing Plan

Change Billing Plan

Change active billing plan for current participant. Takes JSON object containing new plan name (basic, lite, standard or pro) and payment card information. For plans other than basic payment card is required. Payment card details may be specified directly (card object must contain number, exp_year, exp_month and cvc) or by means of a card token generated on client side (card object must contain nonce token). Card token generation is the preferred method, it's payment service provider dependent. Currently server uses Stripe for actual payment processing (see https://stripe.com/docs/stripe-js for client side library).

The default modules for plans:

* basic - hasn't active modules;
* lite has product360 and reviews;
* standard has product360, reviews, rewards;
* pro has product360, reviews, chat, rewards.

The default modules may be set in sys.config. The participant can upgrade the plan at any time. The plan can only be downgraded after 52 weeks of using the current plan. When the plan is changed, the payment is recalculated and fees for used rewards campaign coins. The coins will be convert to сurrency depending on the plan:

* lite - 1point = 0.1 (usd);
* standard - 1point = 0.2 (usd);
* pro - 1point = 0.3 (usd).

The actual currency may be set in sys.config. Default is usd. Payment depends of the participant's plan:

* basic - 0;
* lite - 195;
* standard - 395;
* pro - 495.

PUT /payments-service/participants/current/billing_plan
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Request
{
  "plan": "standard",
  "card": {
    "number": "5200828282828210",
    "exp_month": 12,
    "exp_year": 2019,
    "name": "JANE DOE",
    "cvc": 323
  }
}

Set email for user's notification

User, who was activate the billing plan (or set new card) can set/remove additionals emails for receiving notifications.

PUT /payments-service/participants/notifications/email
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
email Email (“foo@bar.com”) - optional
user_id User ID (“urn:authenticateit:user:email:foo@bar.com”) - optional. If id is user_id then email will be read from user profile
Example Response
[
  "some_user@gmail.com",
  "foo@bar.com",
  "foo1@bar.com"
]

Remove email

POST /payments-service/participants/notifications/delete_email
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
email string Email
Example Response
[
  "some_user@gmail.com",
  "foo1@bar.com"
]

Get participant payment history

API to read payment history of current participant. Returns JSON list of history entries. Each entry has timestamp ts, type of the payment in payment_type field (either subscription or rewards), amount field and card object field. Card object has last four digits of the card number in the last4 field.

GET /payments-service/participants/current/payment_history
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
[
  {
    "card_barnd": "MasterCard",
    "card_exp_month": 12,
    "card_exp_year": 2019,
    "card_last4": "8210",
    "card_name": "JANE DOE",
    "currency": "usd",
    "rows": [
      {
        "amount": "395.00",
        "description": "Selected plan - \"standard\". Paid period: from 2017-03-24 to 2017-04-24"
      },
      {
        "amount": "20.00",
        "description": "Used rewards coins. Paid period: from 2017-03-24 to 2017-04-24"
      }
    ],
    "status": "Payment successful",
    "summary_amount": "415.00",
    "ts": "2017-04-23T21:10:03Z"
  }
]

Terminate contract

GET /participants/:id/contract/terminate
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket

Participant Ethereum Account

Read Ethereum Account

Retrieves Ethereum account information of current participant. Returns JSON with address field (checksum encoded Ethereum address). If participant has no Ethereum account configured, address may be null or missing in the response.

GET /payments-service/participants/current/ethereum
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
  "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}

Update Ethereum Account

Change Ethereum account information of current participant. Accepts JSON object with field address (Ethereum address, or null to clear the address). Responds with updated participant's Ethereum account information. Participant must have no active reward campaigns to change Ethereum address.

PUT /payments-service/participants/current/ethereum
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Request
{
  "address": null
}

Get participant deposit settings

GET /payments-service/participants/deposit/ethereum
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "address": "0x3d74e50Fb155f32d2A477F9068B30C2B28377f8e",
    "unlimited_coins": false,
    "coins": "1250000000000000000000",
    "fee": {
        "source": "invoice",
        "status": "active",
        "ts": "2019-04-05T02:34:35Z",
        "type": "coins",
        "value": "20000000000000000000"
    }
}
Response parameters
Name Type Description
address body Deposit ethereum address
unlimited_coins body Boolean parameter. Optional
coins body Deposit coins value. Optional, 0 by default

User's coins transfers

Add new / update address

POST /user/ethereum/addresses
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
address body Required: Ethereum address
description body Description
Example Request
{
    "address": "0xe40555b43d60656b9510860A11D6bDCDDb8E78A2",
    "description": "My new wallet"
}
Example Response
{
    "list": [
        {
            "address": "0xe40555b43d60656b9510860A11D6bDCDDb8E78A2",
            "description": "My new wallet",
            "ts": "2018-08-30T14:16:07Z"
        }
    ]
}

Get user's addresses

GET /user/ethereum/addresses
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "list": [
        {
            "address": "0xe40555b43d60656b9510860A11D6bDCDDb8E78A2",
            "description": "My new wallet",
            "ts": "2018-08-30T14:16:07Z"
        }
    ]
}

Remove addresses

PUT /user/ethereum/addresses/remove
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
list body Required: Ethereum addresses
Example Request
{
    "list": ["0xe40555b43d60656b9510860A11D6bDCDDb8E78A2"]
}
Example Response
{
    "list": []
}

Get user's balance

GET /payments-service/user/ethereum/balance
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "account_coins": "1949979999999999999934",
    "balance_coins": "10111020000000000000000",
    "coins_fee": {
        "max": "50000000000000000000",
        "min": "1000000000000000000"
    },
    "total_coins": "12060999999999999999934"
}
Return parameters
Name Description
account_coins Coins from user's profile
balance_coins Coins from all user's addresses
total_coins account_coins + account_coins
coins_fee Min and Max values for transaction fee parameter

Transfer coins method

POST /payments-service/user/ethereum/transfer
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
address body Required: Ethereum address
coins body Required: Coins value
fee body Required: Fee value
Example Request
{"address":"0xe40555b43d60656b9510860A11D6bDCDDb8E78A2", "coins":"9000000000000000000", "fee": "1000000000000000000"}
Example Response
{
    "address": "0xe40555b43d60656b9510860A11D6bDCDDb8E78A2",
    "coins": "9000000000000000000",
    "fee": "1000000000000000000",
    "hash": null,
    "id": "urn:authenticateit:transaction_request:9f5885f7-b013-440c-b86e-a247fc8d6ba2",
    "status": "pending",
    "ts": "2018-03-08T09:16:49Z"
}

Read transfers history

GET /payments-service/user/ethereum/transfer/history
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "history": [
        {
            "account": {
                "account": "22334455",
                "bank": "Commonwealth",
                "bsb": "123456",
                "city": "Melbourne",
                "country": "036",
                "description": "My primary account",
                "id": "f50b74b3-8605-4985-af89-20cd0adfe89d",
                "name": "John Smith"
            },
            "coins": "200000000000000000000",
            "converted_value": 0.14,
            "converted_aud_value": 0.4,
            "currency": "aud",
            "hash": "8320be4b7890fdef8c4d0d0f840067eb",
            "id": "urn:authenticateit:transaction_request:9ab1b8e4-307c-44cd-8f42-49220dfb396e",
            "status": "success",
            "ts": "2018-09-03T07:17:00Z",
            "type": "cashout"
        },
        {
            "address": "0xe40555b43d60656b9510860A11D6bDCDDb8E78A2",
            "coins": "500000000000000000000",
            "fee": "44000000000000000000",
            "converted_aud_value": 0.0024809999999999997,
            "hash": "0x73c5528ecc390743329b8c154da42c361f7096335fb62819913ae237650a5c4c",
            "id": "urn:authenticateit:transaction_request:a0ba1883-cbec-4a2c-9659-9a8b0aa7cd3a",
            "status": "success",
            "ts": "2018-08-30T20:46:04Z"
        },
        {
            "coins": "10000000000000000000",
            "hash": "0xb567ada4a95ba99124d5babd45f7e9a74cd4c35e6852b77c81c99b8f841d7ef4",
            "id": "297eb890-bfda-4500-97ba-7c04c795271a",
            "status": "success",
            "ts": "2018-08-30T20:30:28Z",
            "type": "deposit"
        },
        {
            "coins": "10000000000000000000",
            "hash": "0x77800628f6368b8b2d1ee0959d15aadd947651536c8a1a80008a0bc5ce8dbc2a",
            "id": "00ad7965-320a-4772-8f0a-4a8eae6025fb",
            "status": "success",
            "ts": "2018-08-30T20:29:27Z",
            "type": "deposit"
        }
    ]
}

Manual transfer approving

Information on pending transfer will be emailed to a moderator (moderators) who will either approve or reject transfer by clicking on approve/reject links. URLs to approve or reject pending transfer are /user/ethereum/transfer/:code/approve and /user/ethereum/transfer/:code/reject.

Approve transfer

GET /user/ethereum/transfer/:code/approve
Parameters
Name Type Description
code body Required: Code UUID

Reject transfer

GET /user/ethereum/transfer/:code/reject
Parameters
Name Type Description
code body Required: Code UUID

User's deposit address

Get deposit address

GET /user/ethereum/deposit
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "address": "0xAc08558735d2a968f8D7B6a00b37328899dF1f28"
}

User's cashout methods

Get allowed countries and currencies

GET /cashout/countries
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "allowed_countries": [
        {
            "country": "036",
            "currency": "aud"
        }
    ]
}

Convert coins to selected countries currency

GET /cashout/convert_coins
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
coins body Required: Coins value
country body Required: Allowed country
Example Request
GET /cashout/convert_coins?coins=10000000000000000000000&country=036
Example Response
{
    "currency": "AUD",
    "value": 7.55
}

Create new cashout account

POST /cashout/account
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
account body Required: Account object
Example Request
{
  "account": {
    "country": "036",
    "city": "Melbourne",
    "bank": "Test BN",
    "name": "John Smith",
    "bsb": "123456",
    "account": "22334455",
    "description": "My second account"
  }
}
Example Response
{
    "account": "22334455",
    "bank": "Test BN",
    "bsb": "123456",
    "city": "Melbourne",
    "country": "036",
    "description": "My second account",
    "id": "03192aaa-a314-4eed-9d1c-a42bf36cdb70",
    "name": "John Smith"
}

Get cashout accounts

GET /cashout/account
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "accounts": [
        {
            "account": "22334455",
            "bank": "SB",
            "bsb": "123456",
            "city": "Melbourne",
            "country": "036",
            "description": "My second account",
            "id": "1d1af3aa-5d62-49d5-a0d7-9e1a3f34c365",
            "name": "John Smith"
        },
        {
            "account": "22334455",
            "bank": "Commonwealth",
            "bsb": "123456",
            "city": "Melbourne",
            "country": "036",
            "description": "My primary account",
            "id": "f50b74b3-8605-4985-af89-20cd0adfe89d",
            "name": "John Smith"
        }
    ]
}

Update account

PUT /cashout/account
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
account body Required: Account object
id body Required: Account id
Example Request
{
  "account": {
    "country": "036",
    "city": "Melbourne",
    "bank": "SB",
    "name": "John Smith",
    "bsb": "123456",
    "account": "22334455",
    "description": "New descritpion test"
  },
  "id": "1d1af3aa-5d62-49d5-a0d7-9e1a3f34c365"
}
Example Response
{
    "accounts": [
        {
            "account": "22334455",
            "bank": "SB",
            "bsb": "123456",
            "city": "Melbourne",
            "country": "036",
            "description": "New descritpion test",
            "id": "1d1af3aa-5d62-49d5-a0d7-9e1a3f34c365",
            "name": "John Smith"
        },
        {
            "account": "22334455",
            "bank": "Commonwealth",
            "bsb": "123456",
            "city": "Melbourne",
            "country": "036",
            "description": "My primary account",
            "id": "f50b74b3-8605-4985-af89-20cd0adfe89d",
            "name": "John Smith"
        }
    ]
}

Remove account

POST /cashout/account/remove
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
accounts body Required: List of ids
Example Request
{
   "accounts": ["1d1af3aa-5d62-49d5-a0d7-9e1a3f34c365"]
}
Example Response
{
    "accounts": [
        {
            "account": "22334455",
            "bank": "Commonwealth",
            "bsb": "123456",
            "city": "Melbourne",
            "country": "036",
            "description": "My primary account",
            "id": "f50b74b3-8605-4985-af89-20cd0adfe89d",
            "name": "John Smith"
        }
    ]
}

Cashout transaction request

POST /cashout/transfer
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id body Required: Selected account id
coins body Required: Coins
Example Request
{
    "id": "f50b74b3-8605-4985-af89-20cd0adfe89d",
    "coins" : "200000000000000000000"
}
Example Response
{
    "account": {
        "account": "22334455",
        "bank": "Commonwealth",
        "bsb": "123456",
        "city": "Melbourne",
        "country": "036",
        "description": "My primary account",
        "id": "f50b74b3-8605-4985-af89-20cd0adfe89d",
        "name": "John Smith"
    },
    "coins": "200000000000000000000",
    "converted_value": 0.14,
    "currency": "aud",
    "hash": null,
    "id": "urn:authenticateit:transaction_request:9ab1b8e4-307c-44cd-8f42-49220dfb396e",
    "status": "pending",
    "ts": "2018-09-03T07:16:20Z"
}

Converting of coins by current price

GET /rewards/convert/coins
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
coins body Required: Coins
country body Country code
currency body Currency
Example Request
{
    "coins" : "100000000000000000"
}
Example Response
{
    "currency": "aud",
    "value": 0.000024
}

Check promo code

GET /participants/promo_code/check
Parameters
Name Type Description
authenticateit_identity_ticket header Session's ticket
code body Required: Promo code
Example Response
{
    "code": "promo60",
    "days_value": 60
}

Coins TopUp

Conditions for TopUp coins:
1) Participant has a supported currency (currently aud, sgd and usd)
2) Participant had coupled credit card to the account

Get minimal amount value

The method also can be used for checking the availability of TopUp for participant

GET /participants/topup/min_amount
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "amount": 510,
    "coins": "100000000000000000000",
    "currency": "aud"
}

amount - amount in returned currency in cents (510 = $5.10)
coins - how many coins can be bought for this minimum amount
currency - currency for participant

Set/Update TopUp

POST /participants/topup/
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
amount body TopUp amount in cents (510 = $5.10). Non negative integer
minimal_amount body Boolean. If true TopUp with min_amount value will be requested. Default: false
coins_threshold body Required: Coins threshold on deposit. If coins <= coins_threshold TopUp will be requested
frequency body Frequency for requesting TopUp
status body TopUp status. active or inactive

amount must be equal or more than min_amount or minimal_amount must be set. If minimal_amount has been set (true), then amount value will be ignored.
Default frequency is daily. daily - one per 1 day. weekly - one per 7 days, monthly - one per 30 days

Example Request
{
    "minimal_amount":true, 
    "coins_threshold": "10000000000000000000000",
    "frequency": "daily",
    "status": "active"
}
Example Responce
{
    "amount": 0,
    "coins_threshold": "10000000000000000000000",
    "currency": "aud",
    "frequency": "daily",
    "minimal_amount": true,
    "status": "active"
}

Get TopUp settings

GET /participants/topup/
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
    "amount": 109,
    "coins_threshold": "10000000000000000000000",
    "currency": "aud",
    "frequency": "daily",
    "minimal_amount": false,
    "status": "active"
}

Delete TopUp settings

DELETE /participants/topup/
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket

Get TopUp history

GET /participants/topup/history?format=v2
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
format body v2is the last format of history

Each topup history subelement has a status (success, failure or pending) field and sub_type field. Possible value of sub_type is charge, topup or refund.

TopUp chains -
1) Charge (failure) -> Refund (success or failure)
2) Charge (success) -> TopUp (failure) -> Refund (success or failure)
3) Charge (success) -> TopUp (success)

Charge and Refund are synchronous operations and can be marked only success or failure statuses.
TopUp is asynchronous blockchain operation. Possible statuses success, failure or pending

Example Response
[
    {
        "amount": 2022,
        "history": [
            {
                "amount": 2022,
                "charge_id": null,
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:ea3a2403-2157-4043-adf7-51d92f71907f",
                "status": "pending",
                "sub_type": "topup",
                "ts": "2019-05-03T19:51:55Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:ea3a2403-2157-4043-adf7-51d92f71907f",
        "status": "pending",
        "ts": "2019-05-03T19:51:55Z"
    },
    {
        "amount": 22,
        "history": [
            {
                "amount": 2200,
                "charge_id": "ch_1EVtkcEFVOePY2EFQBBtOqDj",
                "coins": "56420000000000000000000",
                "currency": "aud",
                "hash": "ceac3ab7c0c9256cce9b7cb39e0048ff",
                "id": "urn:authenticateit:transaction_request:0c97d9c6-402f-4fd3-8fdb-a34af3148edd",
                "status": "success",
                "sub_type": "topup",
                "topup_history": [
                    {
                        "result": "56420000000000000000000",
                        "status": "done",
                        "ts": "2019-05-03T05:16:14.331Z"
                    },
                    {
                        "order": {
                            "price": "0.0000017",
                            "side": "bid",
                            "size": "56420",
                            "source": "fake_order",
                            "trading_pair_id": "SHPING-ETH",
                            "type": "market"
                        },
                        "status": "cobinhood_done",
                        "total": "56420",
                        "ts": "2019-05-03T05:16:04.291Z"
                    },
                    {
                        "status": "btcmarkets_done",
                        "total": "0.09591436093920491",
                        "ts": "2019-05-03T05:16:04.103Z"
                    },
                    {
                        "status": "init",
                        "ts": "2019-05-03T05:16:03.453Z"
                    }
                ],
                "ts": "2019-05-03T05:16:20Z",
                "type": "topup"
            },
            {
                "amount": 2200,
                "charge_id": "ch_1EVtkcEFVOePY2EFQBBtOqDj",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:0c97d9c6-402f-4fd3-8fdb-a34af3148edd",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-05-03T05:16:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:0c97d9c6-402f-4fd3-8fdb-a34af3148edd",
        "status": "success",
        "ts": "2019-05-03T05:16:00Z"
    },
    {
        "amount": 1500,
        "history": [
            {
                "amount": 150000,
                "charge_id": "ch_1EUWiMEFVOePY2EFQAanmBb7",
                "currency": "aud",
                "hash": "d748ecf0c4c9704fa55def804900081e",
                "id": "urn:authenticateit:transaction_request:4209ca46-e83c-46a0-ae76-e636942b3bfb",
                "status": "success",
                "sub_type": "refund",
                "ts": "2019-04-29T10:28:00Z",
                "type": "topup"
            },
            {
                "amount": 150000,
                "charge_id": "ch_1EUWiMEFVOePY2EFQAanmBb7",
                "currency": "aud",
                "hash": "d748ecf0c4c9704fa55def804900081e",
                "id": "urn:authenticateit:transaction_request:4209ca46-e83c-46a0-ae76-e636942b3bfb",
                "status": "failure",
                "sub_type": "topup",
                "ts": "2019-04-29T10:28:00Z",
                "type": "topup"
            },
            {
                "amount": 150000,
                "charge_id": "ch_1EUWiMEFVOePY2EFQAanmBb7",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:4209ca46-e83c-46a0-ae76-e636942b3bfb",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-04-29T10:28:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:4209ca46-e83c-46a0-ae76-e636942b3bfb",
        "status": "failure",
        "ts": "2019-04-29T10:28:00Z"
    },
    {
        "amount": 20,
        "history": [
            {
                "amount": 2000,
                "charge_id": null,
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:0183600d-a96e-4549-a2ed-21605002b7cd",
                "reason": "Can't charge customer. 2019-02-20T08:21:01Z",
                "status": "failure",
                "sub_type": "charge",
                "ts": "2019-02-20T08:21:01Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:0183600d-a96e-4549-a2ed-21605002b7cd",
        "status": "failure",
        "ts": "2019-02-20T08:21:01Z"
    },
    {
        "amount": 20,
        "history": [
            {
                "amount": 2000,
                "charge_id": null,
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:a6281812-9a69-46b3-861d-12e0ce712fb5",
                "reason": "Can't charge customer. 2019-02-19T08:19:00Z",
                "status": "failure",
                "sub_type": "charge",
                "ts": "2019-02-19T08:19:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:a6281812-9a69-46b3-861d-12e0ce712fb5",
        "status": "failure",
        "ts": "2019-02-19T08:19:00Z"
    },
    {
        "amount": 5.1,
        "history": [
            {
                "amount": 510,
                "charge_id": null,
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:26819ece-5d6f-4f4e-9a64-9f3176956830",
                "reason": "Can't charge customer. 2019-02-18T08:18:00Z",
                "status": "failure",
                "sub_type": "charge",
                "ts": "2019-02-18T08:18:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:26819ece-5d6f-4f4e-9a64-9f3176956830",
        "status": "failure",
        "ts": "2019-02-18T08:18:00Z"
    },
    {
        "amount": 5.1,
        "history": [
            {
                "amount": 510,
                "charge_id": "ch_1E57IDEFVOePY2EFzWCnzEgW",
                "coins": "10631000000000000000000",
                "currency": "aud",
                "hash": "082c32930eb493f481fe686d8b03f683",
                "id": "urn:authenticateit:transaction_request:eaf3a0f7-a970-49b0-88c4-1a1b0198b93c",
                "status": "success",
                "sub_type": "topup",
                "ts": "2019-02-18T08:16:00Z",
                "type": "topup"
            },
            {
                "amount": 510,
                "charge_id": "ch_1E57IDEFVOePY2EFzWCnzEgW",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:eaf3a0f7-a970-49b0-88c4-1a1b0198b93c",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-02-18T08:16:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:eaf3a0f7-a970-49b0-88c4-1a1b0198b93c",
        "status": "success",
        "ts": "2019-02-18T08:16:00Z"
    },
    {
        "amount": 13,
        "history": [
            {
                "amount": 1300,
                "charge_id": "ch_1E5217EFVOePY2EFqlmatmqm",
                "coins": "27505000000000000000000",
                "currency": "aud",
                "hash": "082c32930eb493f481fe686d8b03e91e",
                "id": "urn:authenticateit:transaction_request:fc8e8c52-14d3-4d8f-bd6d-35e9d845304e",
                "status": "success",
                "sub_type": "topup",
                "ts": "2019-02-18T02:38:00Z",
                "type": "topup"
            },
            {
                "amount": 1300,
                "charge_id": "ch_1E5217EFVOePY2EFqlmatmqm",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:fc8e8c52-14d3-4d8f-bd6d-35e9d845304e",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-02-18T02:38:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:fc8e8c52-14d3-4d8f-bd6d-35e9d845304e",
        "status": "success",
        "ts": "2019-02-18T02:38:00Z"
    },
    {
        "amount": 10,
        "history": [
            {
                "amount": 1000,
                "charge_id": null,
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:b13d0cb8-7160-43e3-8ea9-9ca3ac96687f",
                "reason": "Can't charge customer. 2019-02-18T02:36:00Z",
                "status": "failure",
                "sub_type": "charge",
                "ts": "2019-02-18T02:36:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:b13d0cb8-7160-43e3-8ea9-9ca3ac96687f",
        "status": "failure",
        "ts": "2019-02-18T02:36:00Z"
    },
    {
        "amount": 6,
        "history": [
            {
                "amount": 600,
                "charge_id": "ch_1E51wGEFVOePY2EF4iq8Mo4i",
                "coins": "12700000000000000000000",
                "currency": "aud",
                "hash": "082c32930eb493f481fe686d8b03e8f5",
                "id": "urn:authenticateit:transaction_request:9fe8a80e-0454-438c-ad58-172411ec23a7",
                "status": "success",
                "sub_type": "topup",
                "ts": "2019-02-18T02:33:00Z",
                "type": "topup"
            },
            {
                "amount": 600,
                "charge_id": "ch_1E51wGEFVOePY2EF4iq8Mo4i",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:9fe8a80e-0454-438c-ad58-172411ec23a7",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-02-18T02:33:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:9fe8a80e-0454-438c-ad58-172411ec23a7",
        "status": "success",
        "ts": "2019-02-18T02:33:00Z"
    },
    {
        "amount": 5.1,
        "history": [
            {
                "amount": 510,
                "charge_id": "ch_1E4nuHEFVOePY2EFqX3sJopS",
                "coins": "12477000000000000000000",
                "currency": "aud",
                "hash": "082c32930eb493f481fe686d8b03dce2",
                "id": "urn:authenticateit:transaction_request:9b13cdb3-4a35-426d-8c59-2e8fe41883cf",
                "status": "success",
                "sub_type": "topup",
                "ts": "2019-02-17T11:34:00Z",
                "type": "topup"
            },
            {
                "amount": 510,
                "charge_id": "ch_1E4nuHEFVOePY2EFqX3sJopS",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:9b13cdb3-4a35-426d-8c59-2e8fe41883cf",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-02-17T11:34:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:9b13cdb3-4a35-426d-8c59-2e8fe41883cf",
        "status": "success",
        "ts": "2019-02-17T11:34:00Z"
    },
    {
        "amount": 5.1,
        "history": [
            {
                "amount": 510,
                "charge_id": "ch_1E4noTEFVOePY2EFRC9k6SlN",
                "coins": "12484000000000000000000",
                "currency": "aud",
                "hash": "082c32930eb493f481fe686d8b03dbc9",
                "id": "urn:authenticateit:transaction_request:d617971a-dafe-48ef-aeec-f3027c56cf3c",
                "status": "success",
                "sub_type": "topup",
                "ts": "2019-02-17T11:28:00Z",
                "type": "topup"
            },
            {
                "amount": 510,
                "charge_id": "ch_1E4noTEFVOePY2EFRC9k6SlN",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:d617971a-dafe-48ef-aeec-f3027c56cf3c",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-02-17T11:28:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:d617971a-dafe-48ef-aeec-f3027c56cf3c",
        "status": "success",
        "ts": "2019-02-17T11:28:00Z"
    },
    {
        "amount": 5.1,
        "history": [
            {
                "amount": 510,
                "charge_id": "ch_1E4nV7EFVOePY2EFezKLiZXj",
                "coins": "12499000000000000000000",
                "currency": "aud",
                "hash": "082c32930eb493f481fe686d8b03d0fd",
                "id": "urn:authenticateit:transaction_request:7b61db41-dd9e-4f1a-ad92-a49c5e924b03",
                "status": "success",
                "sub_type": "topup",
                "ts": "2019-02-17T11:08:00Z",
                "type": "topup"
            },
            {
                "amount": 510,
                "charge_id": "ch_1E4nV7EFVOePY2EFezKLiZXj",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:7b61db41-dd9e-4f1a-ad92-a49c5e924b03",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-02-17T11:08:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:7b61db41-dd9e-4f1a-ad92-a49c5e924b03",
        "status": "success",
        "ts": "2019-02-17T11:08:00Z"
    },
    {
        "amount": 5.1,
        "history": [
            {
                "amount": 510,
                "charge_id": "ch_1E4mVBEFVOePY2EFbezg6KIf",
                "coins": "12698000000000000000000",
                "currency": "aud",
                "hash": "082c32930eb493f481fe686d8b03c64f",
                "id": "urn:authenticateit:transaction_request:0003b162-c8d7-4f8f-bee5-75fb21f571a7",
                "status": "success",
                "sub_type": "topup",
                "ts": "2019-02-17T10:04:00Z",
                "type": "topup"
            },
            {
                "amount": 510,
                "charge_id": "ch_1E4mVBEFVOePY2EFbezg6KIf",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:0003b162-c8d7-4f8f-bee5-75fb21f571a7",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-02-17T10:04:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:0003b162-c8d7-4f8f-bee5-75fb21f571a7",
        "status": "success",
        "ts": "2019-02-17T10:04:00Z"
    },
    {
        "amount": 5.1,
        "history": [
            {
                "amount": 510,
                "charge_id": "ch_1E4fcPEFVOePY2EFLpjkalnW",
                "coins": "12314000000000000000000",
                "currency": "aud",
                "hash": "082c32930eb493f481fe686d8b03be79",
                "id": "urn:authenticateit:transaction_request:88eb2ea7-f804-4f7e-b34d-8c2664d46e33",
                "status": "success",
                "sub_type": "topup",
                "ts": "2019-02-17T02:43:00Z",
                "type": "topup"
            },
            {
                "amount": 510,
                "charge_id": "ch_1E4fcPEFVOePY2EFLpjkalnW",
                "currency": "aud",
                "hash": null,
                "id": "urn:authenticateit:transaction_request:88eb2ea7-f804-4f7e-b34d-8c2664d46e33",
                "status": "success",
                "sub_type": "charge",
                "ts": "2019-02-17T02:43:00Z",
                "type": "topup"
            }
        ],
        "id": "urn:authenticateit:transaction_request:88eb2ea7-f804-4f7e-b34d-8c2664d46e33",
        "status": "success",
        "ts": "2019-02-17T02:43:00Z"
    }
]

Create manual TopUp request

POST /participants/topup/manual
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
amount body Required: TopUp amount (510 = $5.10). Non negative integer
Example Request
{
    "amount":2000
}

Rate cards

Read rate card

system participant can set id and read card by any account. If id=default method will return the default rate card.
Non system participant can read only self rate card (default card if system participant hadn't preconfigured card for account)

GET /payments-service/participants/rate_card
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Required for system. default or participant id
Example Response
{
    "adjustment": {
        "approved_reviews": "19256000000000000000000",
        "clicks": "14442000000000000000000",
        "completed_video": "16849000000000000000000",
        "impressions_revenue": "144000000000000000000",
        "transactional_data": "28884000000000000000000"
    },
    "id": "urn:authenticateit:rate_card",
    "rate_card": {
        "billable": true,
        "budget": {
            "day": 20,
            "month": 40,
            "week": 30
        },
        "gst": 10,
        "items": [
            {
                "events": [
                    "follow_fb",
                    "visit_link",
                    "visit_social_networks_link"
                ],
                "id": "clicks",
                "name": "Clicks",
                "value": 0.3
            },
            {
                "events": [
                    "watch_video"
                ],
                "id": "completed_video",
                "name": "Completed Video",
                "value": 0.35
            },
            {
                "events": [
                    "send_review"
                ],
                "id": "approved_reviews",
                "name": "Approved Reviews",
                "value": 0.4
            },
            {
                "events": [
                    "scan",
                    "send_scan_location",
                    "view_certificates",
                    "view_image",
                    "view_nutrition_info",
                    "view_popup",
                    "view_status",
                    "view_text"
                ],
                "id": "impressions_revenue",
                "name": "Impressions Revenue",
                "value": 0.003
            },
            {
                "events": [],
                "id": "transactional_data",
                "name": "Transactional Data",
                "value": 0.6
            }
        ],
        "user_rewards": {
            "percents": 0.25
        }
    },
    "type": "rate_card"
}

Set rate card

Method alowed only for system participant

POST /payments-service/participants/rate_card:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Required: default or participant id
billable boolean Required: Billable flag
user_rewards object Required: User rewards options
gst non_neg_integer GST
items array required rate_card items
budget object Budget limits

id = default - default card will be changed
id = <participant_id> - Participant card will be changed

items list should contains items.id and items.value keys.
items.id should be filled acording Settings.
items.value should be non_negative number.

user_rewards is an object. This element should contains user_rewards.percents, user_rewards.coins or user_rewards.value user_rewards.percents - should be non_negative number.
user_rewards.value - should be non_negative number.
user_rewards.coins - should be in coins format

Example Request
{
  "billable": true,
  "budget": {
    "day": 20,
    "week": 30,
    "month": 40
  },
  "gst": 10,
  "items": [
    {
      "id": "clicks",
      "value": 0.1
    },
    {
      "id": "completed_video",
      "value": 0.1
    },
    {
      "id": "approved_reviews",
      "value": 0.1
    },
    {
      "id": "impressions_revenue",
      "value": 0.2
    },
    {
      "id": "transactional_data",
      "value": 0.3
    }
  ],
  "user_rewards": {
    "percents": 0.25
  }
}
Example Response
{
    "adjustment": {
        "approved_reviews": "4811000000000000000000",
        "clicks": "4811000000000000000000",
        "completed_video": "4811000000000000000000",
        "impressions_revenue": "9622000000000000000000",
        "transactional_data": "14433000000000000000000"
    },
    "id": "urn:authenticateit:participant:735879621218609@rate_card",
    "rate_card": {
        "billable": true,
        "budget": {
            "day": 20,
            "month": 40,
            "week": 30
        },
        "gst": 10,
        "items": [
            {
                "events": [
                    "follow_fb",
                    "visit_link",
                    "visit_social_networks_link"
                ],
                "id": "clicks",
                "name": "Clicks",
                "value": 0.1
            },
            {
                "events": [
                    "watch_video"
                ],
                "id": "completed_video",
                "name": "Completed Video",
                "value": 0.1
            },
            {
                "events": [
                    "send_review"
                ],
                "id": "approved_reviews",
                "name": "Approved Reviews",
                "value": 0.1
            },
            {
                "events": [
                    "scan",
                    "send_scan_location",
                    "view_certificates",
                    "view_image",
                    "view_nutrition_info",
                    "view_popup",
                    "view_status",
                    "view_text"
                ],
                "id": "impressions_revenue",
                "name": "Impressions Revenue",
                "value": 0.2
            },
            {
                "events": [],
                "id": "transactional_data",
                "name": "Transactional Data",
                "value": 0.3
            }
        ],
        "user_rewards": {
            "percents": 0.25
        }
    },
    "type": "rate_card"
}

Delete custom rate card

Method allowed only for system participant. system participants can set id and delete participant's card

DELETE /payments-service/participants/rate_card/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Required: participant id

results matching ""

    No results matching ""