> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphapo.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a payment request
> Create a payment request for the client for a specified amount and a configurable expiration time.
Make sure that the URL that you provide in the `url_store` field uses the secure HTTPS protocol, uses domain names (not IP addresses) and is considered clean by VirusTotal and similar scanners.
## OpenAPI
````yaml POST /requests
openapi: 3.0.0
info:
title: Merchant Backend V2
version: '1.0'
description: Documentation for merchant backend processing endpoints
servers:
- url: https://app.alphapo.net/api/v2
security:
- xProcessingKey: []
tags:
- name: Status
- name: Balance
- name: Currencies
- name: Deposit addresses
- name: Withdrawal
- name: Exchange
- name: Invoices
- name: Transactions
paths:
/requests:
post:
tags:
- Payment requests
summary: Create a payment request
description: >-
Create a payment request for the client for a specified amount and a
configurable expiration time.
parameters:
- $ref: '#/components/parameters/XProcessingSignatureHeader'
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
type: string
description: >-
Payment request amount that you want to receive from the
customer.
example: '100.50'
currency:
type: object
description: The currency you want to receive.
required:
- iso
properties:
iso:
type: string
description: >-
Currency ISO code. For the list of all available
currencies, see [Currency
codes](/api-reference/currency-codes#currency-codes-for-payment-requests).
example: EUR
network_name:
type: string
nullable: true
description: >-
Currency network name. Required for cryptocurrencies. Do
not include for fiat currencies. For the list of all
available networks, see [Currency
codes](/api-reference/currency-codes#currency-codes-for-payment-requests).
life_time_duration:
type: integer
nullable: true
description: >-
Payment request lifetime (duration in seconds). Include
**either** this parameter or life_time_datetime. **At least
one** of these fields is required.
example: 3600
life_time_datetime:
type: integer
nullable: true
description: >-
Payment request lifetime (exact expiry timestamp). Include
**either** this parameter or life_time_duration. **At least
one** of these fields is required.
example: 1773768946
payment_currency:
type: object
required:
- iso
description: >-
The currency your customer will pay in. You can set both the
currency and network or just the currency.
properties:
iso:
type: string
description: >-
Currency ISO code. For the list of all available
currencies, see [Currency
codes](/api-reference/currency-codes#currency-codes-for-payment-requests).
network_name:
type: string
nullable: true
description: >-
Currency network name. Do not include for fiat
currencies. For the list of all available networks, see
[Currency
codes](/api-reference/currency-codes#currency-codes-for-payment-requests).
end_user_email:
type: string
description: >-
If the amount the customer pays does not match the amount
that you set for the payment request, AlphaPo will send an
email to this address instructing the customer on how they
can receive a refund. If they paid less, they will receive a
full refund. If they paid more, the customer will get
instructions on how to be refunded the difference.
example: customer@example.com
end_user_reference:
type: string
description: >-
The unique ID of the customer this payment request is for.
You can use it to group payment requests by customer.
description:
type: string
description: Payment request description that the customer will see.
example: 'Order #123'
foreign_id:
type: string
description: >-
Unique foreign ID in your system. Must not contain personal
data, such as the user's name or email address.
example: order_123
url_store:
type: string
description: >-
URL of the store page. The customer can click a button on
the payment form to return to this URL (for example, if they
change their mind or want to pick a different payment
method). We recommend setting this to the URL of the
checkout page.
example: https://example.com/store
url_success:
type: string
description: >-
URL of the success page. The customer will be able to return
to this address once the payment is completed.
example: https://example.com/success
url_failed:
type: string
description: >-
URL of the failed payment page. The customer will be able to
return to this address if the payment fails.
example: https://example.com/fail
required:
- amount
- currency
- life_time_duration
- life_time_datetime
examples:
Fiat:
value:
amount: '100'
currency:
iso: EUR
life_time_duration: 360000
end_user_email: customer@example.com
description: Order 0512
foreign_id: payment_request_123
url_store: https://example.com/store
end_user_reference: user_12345
Cryptocurrency:
value:
amount: '0.0015'
currency:
iso: USDC
network_name: ethereum
life_time_duration: 360000
end_user_email: customer@example.com
description: Order 0511
foreign_id: payment_request_123
url_store: https://example.com/store
end_user_reference: user_12345
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
required:
- id
- amount
- currency
- status
- life_time
- payment_link
properties:
id:
type: string
description: Payment request ID.
example: 0196f6a1-cab2-76fb-84c7-7e9ee9ddf6b4
amount:
type: string
description: Payment request amount.
example: '100.50'
currency:
properties:
iso:
type: string
description: Payment request currency.
example: EUR
network_name:
type: string
nullable: true
description: >-
Network of the selected cryptocurrency. Not
included for fiat currencies.
required:
- iso
status:
type: string
description: >-
For newly created payment request, this will always be
created.
example: created
life_time:
type: string
description: >-
Unix timestamp for when the payment request will
expire, in seconds.
example: 1731427200
payment_currency:
type: object
required:
- iso
description: The currency your customer will pay in.
properties:
iso:
type: string
description: >-
Currency ISO code. For the list of all available
currencies, see [API currency
codes](/api-reference/currency-codes#currency-codes-for-payment-requests).
network_name:
type: string
description: >-
Currency network name. Required for
cryptocurrencies. Do not include for fiat
currencies.
end_user_email:
type: string
description: Customer email provided in the request.
example: customer@example.com
description:
type: string
description: Payment request description.
example: 'Order #123 payment'
payment_link:
type: string
description: Payment request URL.
foreign_id:
type: string
description: Unique payment request ID in your system.
example: uuid string
url_store:
type: string
description: URL of the store page.
url_success:
type: string
description: URL of the success page.
url_failed:
type: string
description: URL of the failed payment page.
examples:
Fiat:
value:
data:
id: 019d511c-9fd2-7e71-b534-74e8abd855f1
amount: '100'
currency:
iso: EUR
status: created
life_time: 1775542323
end_user_email: customer@example.com
description: Order 0512
payment_link: >-
https://payments.alphapo.net/payment/lLXLZ6Q8lCwFFRbyW0C1ET
foreign_id: payment_request_123
url_store: https://example.com/store
end_user_reference: user_12345
Cryptocurrency:
value:
data:
id: 019d511c-1546-7c34-a916-a2610a198448
amount: '0.0015'
currency:
iso: USDC
network_name: ethereum
status: created
life_time: 1775542288
end_user_email: customer@example.com
description: Order 0511
payment_link: >-
https://payments.alphapo.net/payment/8N8_cWBnfAbT12mR5JmPVf
foreign_id: payment_request_123
url_store: https://example.com/store
end_user_reference: user_12345
'400':
description: Duplicate foreign_id.
content:
application/json:
schema:
type: object
title: ErrorResponse
required:
- error
- code
properties:
error:
type: string
description: Human-readable error message.
code:
type: integer
description: HTTP status code.
examples:
ForeignIdAlreadyExists:
summary: Duplicate foreign_id
value:
error: Payment request with this foreign_id already exists.
code: 400
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message.
code:
type: string
description: Error code.
description: >-
Invalid or missing headers. Refer to
[Errors](/api-reference/errors#403-forbidden) for
troubleshooting steps.
examples:
Bad signature header:
value:
error: Bad signature header
code: bad_header_signature
No signature header:
value:
error: No signature header
code: required_header_signature
Bad key header:
value:
error: Bad key header
code: bad_header_key
No key header:
value:
error: No key header
code: required_header_key
Bad content format:
value:
error: Bad content format
code: bad_content_format
Client is not enabled:
value:
error: Client is not enabled
code: client_disabled
Wrong api version:
value:
error: Wrong api version
code: api_disabled
Merchant_disabled:
value:
error: Merchant is disabled.
code: 403
'404':
description: Invalid currency
content:
application/json:
schema:
type: object
title: ErrorResponse
required:
- error
- code
properties:
error:
type: string
description: Human-readable error message.
code:
type: integer
description: HTTP status code.
examples:
CurrencyIsoIncorrect:
summary: Invalid currency.iso
value:
error: The currency.iso is incorrect.
code: 404
PaymentCurrencyIsoIncorrect:
summary: Invalid payment_currency.iso
value:
error: payment_currency.iso is incorrect.
code: 404
'422':
description: Failed validation
content:
application/json:
schema:
type: object
title: ErrorResponse
required:
- error
- code
properties:
error:
type: string
description: Human-readable error message.
code:
type: integer
description: HTTP status code.
examples:
CurrencyIsoMandatory:
summary: Missing currency.iso
value:
error: The iso is a mandatory field.
code: 422
CurrencyIsoDisabled:
summary: Disabled currency.iso
value:
error: The currency.iso is disabled.
code: 422
CurrencyNetworkNameMandatory:
summary: Missing currency.network_name for crypto
value:
error: >-
The currency.network_name field is mandatory for crypto
currencies.
code: 422
CurrencyNetworkNotSupported:
summary: Unsupported currency and network combination
value:
error: The combination of currency and network is not supported.
code: 422
AmountMandatory:
summary: Missing amount
value:
error: The amount field is mandatory.
code: 422
AmountMinimum:
summary: Amount below minimum
value:
error: The minimum amount is EUR.
code: 422
AmountMaximum:
summary: Amount above maximum
value:
error: The maximum amount is EUR.
code: 422
AmountTooManyDecimals:
summary: Too many decimal places
value:
error: >-
The amount for cannot have more than
decimal places.
code: 422
PeriodRequired:
summary: Missing life time fields
value:
error: >-
It is obligatory - to fill in life_time_date_time or
life_time_duration.
code: 422
PeriodOnlyOneAllowed:
summary: Both life time fields provided
value:
error: >-
Only one of fields life_time_date_time and
life_time_duration should be field.
code: 422
LifeSpanTooShort:
summary: Lifespan below minimum
value:
error: >-
The lifespan must be longer than or equal to
{minutes/days}.
code: 422
LifeSpanTooLong:
summary: Lifespan above maximum
value:
error: >-
The lifespan must be shorter than or equal
{minutes/days}.
code: 422
EndUserEmailIncorrect:
summary: Invalid email
value:
error: The email address is incorrect.
code: 422
PaymentCurrencyEmpty:
summary: Empty payment_currency
value:
error: payment_currency must not be empty if provided.
code: 422
PaymentCurrencyIsoMustBeCrypto:
summary: payment_currency.iso must be cryptocurrency
value:
error: payment_currency.iso must be a cryptocurrency.
code: 422
PaymentCurrencyIsoEmpty:
summary: Empty payment_currency.iso
value:
error: payment_currency.iso must not be empty if provided.
code: 422
PaymentCurrencyIsoDisabled:
summary: Disabled payment_currency.iso
value:
error: payment_currency.iso is disabled.
code: 422
ExchangeRateUnavailable:
summary: Exchange rate unavailable
value:
error: >-
Exchange rate is not available between and
.
code: 422
PaymentCurrencyNetworkEmpty:
summary: Empty payment_currency.network_name
value:
error: >-
payment_currency.network_name must not be empty if
provided.
code: 422
PaymentCurrencyNetworkWithoutIso:
summary: payment_currency.network_name without iso
value:
error: >-
payment_currency.network_name cannot be specified without
payment_currency.iso.
code: 422
PaymentCurrencyNetworkNotSupported:
summary: Unsupported payment currency and network combination
value:
error: The combination of currency and network is not supported.
code: 422
DescriptionTooLong:
summary: Description too long
value:
error: The description must be 255 characters or less.
code: 422
DescriptionEmpty:
summary: Empty description
value:
error: The description must not be empty if provided.
code: 422
ForeignIdTooLong:
summary: foreign_id too long
value:
error: Foreign ID must be 255 characters or less.
code: 422
ForeignIdEmpty:
summary: Empty foreign_id
value:
error: The foreign_id must not be empty if provided.
code: 422
UrlStoreInvalid:
summary: Invalid url_store
value:
error: The url_store is invalid.
code: 422
UrlStoreTooLong:
summary: url_store too long
value:
error: The url_store must be 255 characters or less.
code: 422
UrlSuccessInvalid:
summary: Invalid url_success
value:
error: The url_success is invalid.
code: 422
UrlSuccessTooLong:
summary: url_success too long
value:
error: The url_success must be 255 characters or less.
code: 422
UrlFailedInvalid:
summary: Invalid url_failed
value:
error: The url_failed is invalid.
code: 422
UrlFailedTooLong:
summary: url_failed too long
value:
error: The url_failed must be 255 characters or less.
code: 422
EndUserReferenceMandatory:
summary: Missing end_user_reference
value:
error: The end_user_reference must not be empty if provided.
code: 422
EndUserReferenceTooLong:
summary: end_user_reference too long
value:
error: The end_user_reference must be 255 characters or less.
code: 422
servers:
- url: https://app.alphapo.net/api/payments/v1
components:
parameters:
XProcessingSignatureHeader:
name: X-Processing-Signature
in: header
required: true
description: >-
Hex-encoded HMAC-SHA512 signature of the request body, [generated using
your secret key](/api-reference/authentication).
schema:
type: string
securitySchemes:
xProcessingKey:
type: apiKey
description: Your [API key](/merchant-administration/generate-and-activate-api-keys).
in: header
name: X-Processing-Key
````