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.
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.
What is the payment intended for?
The title of the payment. Max 160 characters.
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.
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
priceis set at0and therefore the payment is free, but customers can enter an amount of their choice. - Your
priceis set at a minimum and customers can enter a higher amount, but no lower amount.
false, the price is fixed.
The content category.
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.
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.
A URL of an image that serves as a background image of the payment. Recommended size is 600x800 pixels.
A subscription will periodically collect the price from a customer.
The frequency/period of the subscription.
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.
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.
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.
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.
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": "2019-08-19T03:30:45+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.
The identifier of the payment to be retrieved.
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": "2019-08-19T03:30:45+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.
The identifier of the payment to be updated.
What is the payment intended for?
The title of the payment. Max 160 characters.
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.
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
priceis set at0and therefore the payment is free, but customers can enter an amount of their choice. - Your
priceis set at a minimum and customers can enter a higher amount, but no lower amount.
false, the price is fixed.
The content category.
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.
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.
A URL of an image that serves as a background image of the payment. Recommended size is 600x800 pixels.
A subscription will periodically collect the price from a customer.
The frequency/period of the subscription.
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.
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.
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.
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.
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": "2019-08-19T03:30:45+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.
The identifier of the payment to be deleted.
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.
The identifier of the transaction to be retrieved.
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": "2019-08-19T03:30:45+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"
}