Uhmi API

The Uhmi API uses standard HTTP verbs and is organized around REST. It has predictable resource-oriented URLs and all request and response payloads are formatted as JSON. If you have any questions, please don’t hesitate to contact our dev team at dev@uhmi.io.

Authentication

The Uhmi API uses API keys to authenticate requests. Your API key is automatically generated upon creating a sell account and can be viewed and managed in your account.

Your API key is unique and it is therefore important that you keep it private. Do not share in publicly accessible areas such as GitHub, client-side code and so forth. If your API key does become compromised, you can always renew your key. Just don’t forget to incorporate your new key into your code, because your old API key will no longer work.

All requests must be made over HTTPS — calls made over plain HTTP will fail.

Copy
curl -X POST https://uhmi.io/api/v1/payments \
-H 'Authorization: Bearer <API Key>' // Replace “<API Key>” with your own API Key
$uhmi = new Uhmi;
$uhmi->setApiKey('<API Key>'); // Replace “<API Key>” with your own API Key

HTTP status codes

The Uhmi API uses HTTP status codes to indicate whether an API request has been successful. An unsuccessful request will return in JSON format with the corresponding HTTP status code. You can figure out what went wrong by using the HTTP status code and the error description.

200 - OK Success.
201 - Created The payment was created successfully.
400 - Bad Request The request can not be processed due to a missing or incorrect parameter.
401 - Unauthorized The authentication has failed. Check your API key.
403 - Forbidden The request is forbidden. This may occur when HTTPS is not used.
404 - Not Found The requested resource could not be found. For example, if you try to retrieve a non-existent payment.
405 - Method Not Allowed You have used a method that is not supported (e.g. GET, POST).
415 - Unsupported Media Type The encoding of your request has a media type which is not supported. Make sure you use UTF-8.
429 - Too Many Requests You have sent too many requests in a given amount of time. Please try again in a moment.
5xx Something went wrong on our end. Please try again. 
"error": {
    "code": 400,
    "message": "The 'price' parameter is invalid or missing."
}

Payments

Payments can represent content, donations and subscriptions and are identified by a unique, random ID. These payment IDs are used in combination with the Widget.js to present the corresponding payment to your customers.

Create payment

To create content, donations or subscriptions you need to create a payment. After successfully creating a payment, we’ll return a unique payment ID. Store the payment ID in, for example, your database. This payment ID represents the newly created payment.

POST
/api/v1/payments
type
string
Required

What is the payment intended for?

Possible values:
content
donation
title
string
Required

The title of the payment. Max 160 characters.

price
float
Required

The price of the payment. For example 0.25 if you would want to charge €0,25. The minimum price is 0.01 and maximum price is 150. When you enter 0, the payment is free.

pwyw
boolean
Optional

If set to true, you give your customers the option to fill in their own price a.k.a. Pay What You Want. This has two variations:

  • Your price is set at 0 and therefore the payment is free, but customers can enter an amount of their choice.
  • Your price is set at a minimum and customers can enter a higher amount, but no lower amount.
If set to false, the price is fixed.

Default value:
false
category
string
Optional

The content category.

Possible values:
video
movie
vlog
animation
audio
music
podcast
audiobook
reading
article
ebook
blog
gaming
game
art
photo
design
software
donation
other
refundable
boolean
Optional

You have the option whether the item is refundable or not. When chosen false, we will clearly indicate to the customers that this item is non-refundable. When true, the customer has 24 hours to request a refund.
Not possible in combination with subscription.

Default value:
true
repeatable
boolean
Optional

The option to pay multiple times for a single payment. For content, you may want to set it to false so that a customer won't have to pay each time in order to access the content. For donations, you may want to set it to true to allow customers to donate multiple times.

Default value:
false
cover
string
Optional

A URL of an image that serves as a background image of the payment. Recommended size is 600x800 pixels.

subscription
array
Optional

A subscription will periodically collect the price from a customer.

Possible values:
interval
interval_count
trial_days
+Show child parameters
interval
string
Required

The frequency/period of the subscription.

Possible values:
day
week
month
year
interval_count
integer
Optional

The number of intervals of the frequency/period. For example, when interval=month and interval_count=3 the subscription price will be collected every 3 months. Maximum number of intervals is 52.

Default value:
1
trial_days
integer
Optional

The number of trial period days. The subscription price will be collected for the first time after the trial period ends. If the subscriber cancels before the trial period is over, they won't be billed at all. Maximum number of trial period days is 365.

Default value:
0
metadata
array
Optional

Add additional data to the payment. This is intended for your own administration and is invisible to customers. You can add up to 1kb of additional data.

success_url
string
Required

After a payment took place the Widget.js will automatically send a request to this URL, along with a transaction ID. With this transaction ID, you can verify if the transaction was successful. When successful, you can then, for example, return the content to present to your customer.

Copy
curl -X POST https://uhmi.io/api/v1/payments \
-H 'Authorization: Bearer <API Key>' \ // Replace “<API Key>” with your own API Key
-d 'type=content' \
-d 'title=My video' \
-d 'price=0.25' \
-d 'pwyw=true' \
-d 'category=video' \
-d 'refundable=true' \
-d 'repeatable=false' \
-d 'cover=https://yourwebsite.com/images/image.png' \
-d 'metadata[video_id]=8690' \
-d 'success_url=https://yourwebsite.com/success'
$uhmi = new Uhmi;
$uhmi->setApiKey('<API Key>'); // Replace “<API Key>” with your own API Key

$payment = $uhmi->createPayment(array(
    'type' => 'content',
    'title' => 'My video',
    'price' => 0.25,
    'pwyw' => true,
    'category' => 'video',
    'refundable' => true,
    'repeatable' => false,
    'cover' => 'https://yourwebsite.com/images/image.png',
    'metadata' => array('video_id' => '8690'),
    'success_url' => 'https://yourwebsite.com/success'
));

Response

{
    "payment_id": "07LygN2WrLPjX1FOnqHfs5xuxcuAwK",
    "status": "active",
    "created_at": "2020-08-09T22:46:15+00:00", // in UTC
    "type": "content",
    "title": "My video",
    "price": 0.25,
    "pwyw": true,
    "category": "video",
    "refundable": true,
    "repeatable": false,
    "cover": "https://yourwebsite.com/images/image.png",
    "metadata": {
        "video_id": "8690"
    },
    "success_url": "https://yourwebsite.com/success"
}

Get payment

Retrieve the details of a single, existing payment by using the unique payment ID that was returned from creating a payment.

GET
/api/v1/payments/:payment_id
payment_id
string
Required

The identifier of the payment to be retrieved.

Copy
curl https://uhmi.io/api/v1/payments/07LygN2WrLPjX1FOnqHfs5xuxcuAwK \
-H 'Authorization: Bearer <API Key>' // Replace “<API Key>” with your own API Key
$uhmi = new Uhmi;
$uhmi->setApiKey('<API Key>'); // Replace “<API Key>” with your own API Key

$payment = $uhmi->getPayment('07LygN2WrLPjX1FOnqHfs5xuxcuAwK');

Response

{
    "payment_id": "07LygN2WrLPjX1FOnqHfs5xuxcuAwK",
    "status": "active",
    "created_at": "2020-08-09T22:46:15+00:00", // in UTC
    "type": "content",
    "title": "My video",
    "price": 0.25,
    "pwyw": true,
    "category": "video",
    "refundable": true,
    "repeatable": false,
    "cover": "https://yourwebsite.com/images/image.png",
    "metadata": {
        "video_id": "8690"
    },
    "success_url": "https://yourwebsite.com/success"
}

Update payment

Use the unique payment ID that was returned from creating a payment to update the values of an existing payment and the parameters passed. Any parameters not provided will be left unchanged.

PATCH
/api/v1/payments/:payment_id
payment_id
string
Required

The identifier of the payment to be updated.

type
string
Required

What is the payment intended for?

Possible values:
content
donation
title
string
Required

The title of the payment. Max 160 characters.

price
float
Required

The price of the payment. For example 0.25 if you would want to charge €0,25. The minimum price is 0.01 and maximum price is 150. When you enter 0, the payment is free.

pwyw
boolean
Optional

If set to true, you give your customers the option to fill in their own price a.k.a. Pay What You Want. This has two variations:

  • Your price is set at 0 and therefore the payment is free, but customers can enter an amount of their choice.
  • Your price is set at a minimum and customers can enter a higher amount, but no lower amount.
If set to false, the price is fixed.

Default value:
false
category
string
Optional

The content category.

Possible values:
video
movie
vlog
animation
audio
music
podcast
audiobook
reading
article
ebook
blog
gaming
game
art
photo
design
software
donation
other
refundable
boolean
Optional

You have the option whether the item is refundable or not. When chosen false, we will clearly indicate to the customers that this item is non-refundable. When true, the customer has 24 hours to request a refund.
Not possible in combination with subscription.

Default value:
true
repeatable
boolean
Optional

The option to pay multiple times for a single payment. For content, you may want to set it to false so that a customer won't have to pay each time in order to access the content. For donations, you may want to set it to true to allow customers to donate multiple times.

Default value:
false
cover
string
Optional

A URL of an image that serves as a background image of the payment. Recommended size is 600x800 pixels.

subscription
array
Optional

A subscription will periodically collect the price from a customer.

Possible values:
interval
interval_count
trial_days
+Show child parameters
interval
string
Required

The frequency/period of the subscription.

Possible values:
day
week
month
year
interval_count
integer
Optional

The number of intervals of the frequency/period. For example, when interval=month and interval_count=3 the subscription price will be collected every 3 months. Maximum number of intervals is 52.

Default value:
1
trial_days
integer
Optional

The number of trial period days. The subscription price will be collected for the first time after the trial period ends. If the subscriber cancels before the trial period is over, they won't be billed at all. Maximum number of trial period days is 365.

Default value:
0
metadata
array
Optional

Add additional data to the payment. This is intended for your own administration and is invisible to customers. You can add up to 1kb of additional data.

success_url
string
Required

After a payment took place the Widget.js will automatically send a request to this URL, along with a transaction ID. With this transaction ID, you can verify if the transaction was successful. When successful, you can then, for example, return the content to present to your customer.

Copy
curl -X PATCH https://uhmi.io/api/v1/payments/07LygN2WrLPjX1FOnqHfs5xuxcuAwK \
-H 'Authorization: Bearer <API Key>' \ // Replace “<API Key>” with your own API Key
-d 'type=content' \
-d 'title=My video' \
-d 'price=0.25' \
-d 'pwyw=true' \
-d 'category=video' \
-d 'refundable=true' \
-d 'repeatable=false' \
-d 'cover=https://yourwebsite.com/images/image.png' \
-d 'metadata[video_id]=8690' \
-d 'success_url=https://yourwebsite.com/success'
$uhmi = new Uhmi;
$uhmi->setApiKey('<API Key>'); // Replace “<API Key>” with your own API Key

$payment = $uhmi->updatePayment(array(
    'payment_id' => '07LygN2WrLPjX1FOnqHfs5xuxcuAwK',
    'type' => 'content',
    'title' => 'My video',
    'price' => 0.25,
    'pwyw' => true,
    'category' => 'video',
    'refundable' => true,
    'repeatable' => false,
    'cover' => 'https://yourwebsite.com/images/image.png',
    'metadata' => array('video_id' => '8690'),
    'success_url' => 'https://yourwebsite.com/success'
));

Response

{
    "payment_id": "07LygN2WrLPjX1FOnqHfs5xuxcuAwK",
    "status": "active",
    "created_at": "2020-08-09T22:46:15+00:00", // in UTC
    "type": "content",
    "title": "My video",
    "price": 0.25,
    "pwyw": true,
    "category": "video",
    "refundable": true,
    "repeatable": false,
    "cover": "https://yourwebsite.com/images/image.png",
    "metadata": {
        "video_id": "8690"
    },
    "success_url": "https://yourwebsite.com/success"
}

Delete payment

This permanently deletes a payment and cannot be undone.

DELETE
/api/v1/payments/:payment_id
payment_id
string
Required

The identifier of the payment to be deleted.

Copy
curl -X DELETE https://uhmi.io/api/v1/payments/07LygN2WrLPjX1FOnqHfs5xuxcuAwK \
-H 'Authorization: Bearer <API Key>' // Replace “<API Key>” with your own API Key
$uhmi = new Uhmi;
$uhmi->setApiKey('<API Key>'); // Replace “<API Key>” with your own API Key

$payment = $uhmi->deletePayment('07LygN2WrLPjX1FOnqHfs5xuxcuAwK');

Response

'Payment deleted'

Transactions

Transactions occur when payments take place.

Get transaction

Retrieve the details of a single, existing transaction by using the unique transaction ID that was returned after a successful payment.

GET
/api/v1/transactions/:transaction_id
transaction_id
string
Required

The identifier of the transaction to be retrieved.

Copy
curl https://uhmi.io/api/v1/transactions/V2LBXVPKH86ERIRSY \
-H 'Authorization: Bearer <API Key>' // Replace “<API Key>” with your own API Key
$uhmi = new Uhmi;
$uhmi->setApiKey('<API Key>'); // Replace “<API Key>” with your own API Key

$payment = $uhmi->getPayment('07LygN2WrLPjX1FOnqHfs5xuxcuAwK');

Response

{
    "payment_id": "07LygN2WrLPjX1FOnqHfs5xuxcuAwK",
    "status": "paid",
    "created_at": "2020-08-09T22:46:15+00:00", // in UTC
    "type": "content",
    "title": "My video",
    "price": 0.25,
    "pwyw": true,
    "category": "video",
    "refundable": true,
    "repeatable": false,
    "cover": "https://yourwebsite.com/images/image.png",
    "metadata": {
        "video_id": "8690"
    },
    "success_url": "https://yourwebsite.com/success"
}

Questions?

Send us an email. We’re happy to help with your code or any other questions you might have!

Contribute.

Send us an email. We’re always looking to improve our code and documentation!