Skip to content

Start a payment for an order

POST
/public/stores/{storeRef}/payments/initiate
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/public/stores/example/payments/initiate \
--header 'Content-Type: application/json' \
--header 'x-storefront-api-key: <x-storefront-api-key>' \
--data '{ "order_code": "example", "provider_code": "example" }'

Starts a payment attempt for an order that is awaiting payment, through one of the store’s enabled gateways, and returns the page to send the shopper to. Every gateway answers with the same shape: redirect the shopper to redirect_url, then poll the payment state until the status changes. The attempt expires after a while; start a new one to retry. Fails with 404 when the order is not found, and with 400 when it is not awaiting payment, the gateway is not enabled or not configured for the store, or the order’s currency is not supported.

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
order_code
required

Orders.order_code of the order to charge

string
provider_code
required

Gateway provider code, e.g. “onepay”, “momo”

string

Example generated

{
"order_code": "example",
"provider_code": "example"
}
Media typeapplication/json
object
payment_id
required

ID of the payment attempt that was created.

number
redirect_url
required

The gateway’s payment page. Redirect the shopper to it exactly as returned: the URL is opaque and, for some gateways, carries signed parameters and the return address, so do not parse or modify it. The shopper returns to the store’s order page afterwards.

string

Example generated

{
"payment_id": 1,
"redirect_url": "example"
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The resource does not exist in this store.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}