Pay.com API (Beta) (1.0.0)

Pay.com Support: support@pay.com URL: https://pay.com

Get started

Pay.com REST APIs use standard HTTP verbs, authentication and response codes. We use JSON-encoded requests and responses.

You can consume the APIs directly using your favorite HTTP/REST library.

Encryption

All HTTP-layer services and protocols (e.g. HTTP) within the Pay.com API are using TLS 1.2.

Webhooks

When an event occurs, we send you a webhook notification to tell you what's happened so you can take action and keep your business running smoothly.

The optional webhook_url parameter

On all requests, the parameter defines where we will send payment status updates to. If not provided, the default URL that was setup on your Space account will be used.

Local testing

The webhook_url must be reachable from Pay.com's point of view, so you cannot use localhost, If you want to use webhook during development on localhost, you must use a tool like ngrok to have the webhooks delivered to your local machine.

Snowflakes

Pay.com utilizes Twitter's snowflake format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Pay.com. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. (Shout-out to Discord).

Transaction Statuses

Payments

STATUS DESCRIPTION
AUTHORIZED The payment is authorized, funds are awaiting capture
AUTHORIZATION_EXPIRED The authorization exceeded maximal duration and was cancelled.
CANCELLED The authroization on the funds has been cancelled, there are no more funds available for capturing
CAPTURED The entire authorized amount has been captured
CREATED The payment was created in the system, but no action has been done so far
DECLINED The payment was declined
ERROR An error occurred while proccessing the payment
EXPIRED No action was taken and the payment request expired
PENDING The payment has been sent for processing and pending response
REFUNDED The payment has been refunded

Payouts

STATUS DESCRIPTION
APPROVED The payout was approved and funds were sent to the consumer
CREATED The payout was created in the system, but no action has been done so far
DECLINED The payout was declined
ERROR An error occurred while proccessing the payout
PENDING The payout has been sent for processing and pending response

Authentication

API Key

Unless explicitly stated, all endpoints require authentication using your API Key. You can find your API keys, and generate new ones, in your Space account.

Format

  • Sandbox example_for_sandbox_key
  • Production example_for_production_key
Security Scheme Type API Key
Header parameter name: Authorization

Payments

Process and manage payments from a variety of sources and to various destinations all within one integration.

Create a payment

Create a payment.

Request
Security:
Request Body schema: application/json
type
string
Default: "regular"

The type of the payment, if set to recurring or installment, and source.type=checkout, source.checkout.setup_future_usage will be ignored.

Enum: "regular" "recurring" "moto" "installment"
object

Details of the source the payment method will be recieved from.

amount
number >= 0

The amount to authorize (and possibly capture).

currency
string 3 characters

The 3 characters (string) or 3 digits (code) of the currency in ISO 4217 format, e.g. use USD or 240 for US dollars.

capture_method
string
Default: "immediately"

Controls when the funds will be captured from the consumer's payment method.

Enum: "immediately" "manual" "delayed"
descriptor
string <= 25 characters

A description of the payment, to be displayed in the cardholder’s statement, in order to identify your business name and transaction.

object

The consumer's details, link to existing consumers will be lookuped up by the id if provided, or the email.

consumer_id
string

Pay.com unique identifier of the user, if provided, consumer object will be ignored.

object

Shipping details.

object

Address details.

webhook_url
string

Set the webhook URL on a specific payment level, where we will send payment status updates to.

reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number. (saved, query)

echo
string <= 255 characters

Any value up to 255 chars long will be returned within the response. (not saved, not query)

metadata
object

A set of key-value pairs that you can attach to the payment request. This can be useful for storing additional information in a structured format. (saved, not query)

Responses
201Payment processed
202Payment request accepted, further action required
400Bad request - the Pay.com API was unable to process your request
401Unauthorized - authentication failed, check your API key
403Forbidden - no access to the requested payment method, consumer or checkout
404Not found - requested payment method, consumer or checkout not found
422Unprocessable entity - the Pay.com API has failed to process the request due to invalid data/entity
429Too many requests – Your request has hit a rate limit, please wait for a bit and retry
post/payments
Request samples
application/json
{
  • "type": "regular",
  • "source": {},
  • "amount": 120,
  • "currency": "USD",
  • "capture_method": "immediately",
  • "descriptor": "Pay.com Payment Services",
  • "consumer": {
    },
  • "consumer_id": "82445909165604864",
  • "shipping": {
    },
  • "billing": {
    },
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "82847909155634862",
  • "resource": "payment",
  • "created_at": "2021-06-01T10:40:45.621Z",
  • "type": "regular",
  • "status": "CAPTURED",
  • "consumer": "82445909165604864",
  • "amount": 120,
  • "amount_capturable": 0,
  • "amount_received": 120,
  • "currency": "USD",
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}

Capture a payment

Captures a payment if supported by the payment method.

Request
Security:
path Parameters
id
required
string

The related authorized payment identifier

Request Body schema: application/json
amount
number >= 0

The amount to capture. If not specified or 0, the full captureable (remaining) amount will be captured.

reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number. (saved, query)

echo
string <= 255 characters

Any value up to 255 chars long will be returned within the response. (not saved, not query)

metadata
object

A set of key-value pairs that you can attach to the payment request. This can be useful for storing additional information in a structured format. (saved, not query)

Responses
201Capture processed
400Bad request - the Pay.com API was unable to process your request
401Unauthorized - authentication failed, check your API key
403Forbidden - no access to the requested authorized payment
404Not found - related authorized payment not found
422Unprocessable entity - the Pay.com API has failed to process the request due to invalid data/entity
429Too many requests – Your request has hit a rate limit, please wait for a bit and retry
post/payments/{id}/capture
Request samples
application/json
{
  • "amount": 120,
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "82847909155634862",
  • "resource": "payment",
  • "created_at": "2021-06-01T10:40:45.621Z",
  • "type": "regular",
  • "status": "CAPTURED",
  • "consumer": "82445909165604864",
  • "amount": 120,
  • "amount_capturable": 0,
  • "amount_received": 120,
  • "currency": "USD",
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}

Refund a payment

Refund a payment if supported by the payment method.

Request
Security:
path Parameters
id
required
string

The related payment identifier

Request Body schema: application/json
amount
number >= 0

The amount to refund. If not specified or 0, the full captured amount will be refunded.

reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number. (saved, query)

echo
string <= 255 characters

Any value up to 255 chars long will be returned within the response. (not saved, not query)

metadata
object

A set of key-value pairs that you can attach to the payment request. This can be useful for storing additional information in a structured format. (saved, not query)

Responses
201Refund processed
400Bad request - the Pay.com API was unable to process your request
401Unauthorized - authentication failed, check your API key
403Forbidden - no access to the requested payment
404Not found - related payment not found
422Unprocessable entity - the Pay.com API has failed to process the request due to invalid data/entity
429Too many requests – Your request has hit a rate limit, please wait for a bit and retry
post/payments/{id}/refund
Request samples
application/json
{
  • "amount": 120,
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "82847909155634862",
  • "resource": "payment",
  • "created_at": "2021-06-01T10:40:45.621Z",
  • "type": "regular",
  • "status": "REFUNDED",
  • "consumer": "82445909165604864",
  • "amount": 120,
  • "amount_capturable": 0,
  • "amount_received": 120,
  • "currency": "USD",
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}

Cancel a payment

Cancel a payment if supported by the payment method.

Request
Security:
path Parameters
id
required
string

The related authorized payment identifier

Request Body schema: application/json
amount
number >= 0

The amount to cancel. If not specified or 0, the full captureable (remaining) amount will be cancelled.

reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number. (saved, query)

echo
string <= 255 characters

Any value up to 255 chars long will be returned within the response. (not saved, not query)

metadata
object

A set of key-value pairs that you can attach to the payment request. This can be useful for storing additional information in a structured format. (saved, not query)

Responses
201Cancellation processed
400Bad request - the Pay.com API was unable to process your request
401Unauthorized - authentication failed, check your API key
403Forbidden - no access to the requested authorized payment
404Not found - related authorized payment not found
422Unprocessable entity - the Pay.com API has failed to process the request due to invalid data/entity
429Too many requests – Your request has hit a rate limit, please wait for a bit and retry
post/payments/{id}/cancel
Request samples
application/json
{
  • "amount": 120,
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "82847909155634862",
  • "resource": "payment",
  • "created_at": "2021-06-01T10:40:45.621Z",
  • "type": "regular",
  • "status": "CANCELLED",
  • "consumer": "82445909165604864",
  • "amount": 120,
  • "amount_capturable": 0,
  • "amount_received": 120,
  • "currency": "USD",
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}

Create a subsequent recurring payment

Create a subsequent recurring payment based related to an initial recurring payment.

Request
Security:
path Parameters
id
required
string

The related initial recurring payment identifier or the previous subsequent recurring payment

Request Body schema: application/json
amount
number >= 0

The amount to capture. If not specified or 0, the full captureable (remaining) amount will be captured.

capture_method
string
Default: "immediately"

Controls when the funds will be captured from the consumer's payment method.

Enum: "immediately" "manual" "delayed"
reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number. (saved, query)

echo
string <= 255 characters

Any value up to 255 chars long will be returned within the response. (not saved, not query)

metadata
object

A set of key-value pairs that you can attach to the payment request. This can be useful for storing additional information in a structured format. (saved, not query)

Responses
201Recurring subsequent payment processed
400Bad request - the Pay.com API was unable to process your request
401Unauthorized - authentication failed, check your API key
403Forbidden - no access to the requested initial recurring payment
404Not found - related initial recurring payment not found
422Unprocessable entity - the Pay.com API has failed to process the request due to invalid data/entity
429Too many requests – Your request has hit a rate limit, please wait for a bit and retry
post/payments/{id}/recurring
Request samples
application/json
{
  • "amount": 120,
  • "capture_method": "immediately",
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "82847909155634862",
  • "resource": "payment",
  • "created_at": "2021-06-01T10:40:45.621Z",
  • "type": "recurring",
  • "status": "CAPTURED",
  • "consumer": "82445909165604864",
  • "amount": 120,
  • "amount_capturable": 0,
  • "amount_received": 120,
  • "currency": "USD",
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}

Payouts

Process and manage payouts from a variety of sources and to various destinations all within one integration.

Request a payout

Transfer funds to your customer.

Request
Security:
Request Body schema: application/json
required
object

Details of the source or destination payment method.

amount
required
number >= 0

The amount to refund. If not specified or 0, the full captured amount will be refunded.

currency
required
string 3 characters

The 3 characters (string) or 3 digits (code) of the currency in ISO 4217 format, e.g. use USD or 240 for US dollars.

descriptor
string <= 25 characters

A description of the payment, to be displayed in the cardholder’s statement, in order to identify your business name and transaction.

object

The consumer's details, link to existing consumers will be lookuped up by the id if provided, or the email.

consumer_id
string

Pay.com unique identifier of the user, if provided, consumer object will be ignored.

object

Address details.

webhook_url
string

Set the webhook URL on a specific payment level, where we will send payment status updates to.

reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number. (saved, query)

echo
string <= 255 characters

Any value up to 255 chars long will be returned within the response. (not saved, not query)

metadata
object

A set of key-value pairs that you can attach to the payment request. This can be useful for storing additional information in a structured format. (saved, not query)

Responses
201Payout processed
400Bad request - the Pay.com API was unable to process your request
401Unauthorized - authentication failed, check your API key
403Forbidden - no access to the requested payment method or consumer
404Not found - requested payment method or consumer not found
422Unprocessable entity - the Pay.com API has failed to process the request due to invalid data/entity
429Too many requests – Your request has hit a rate limit, please wait for a bit and retry
post/payouts
Request samples
application/json
{
  • "payment_method": {
    },
  • "amount": 120,
  • "currency": "USD",
  • "descriptor": "Pay.com Payment Services",
  • "consumer": {
    },
  • "consumer_id": "82445909165604864",
  • "billing": {
    },
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "82847909155634862",
  • "resource": "payout",
  • "created_at": "2021-06-01T10:40:45.621Z",
  • "status": "APPROVED",
  • "consumer": "82445909165604864",
  • "amount": 120,
  • "currency": "USD",
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}

Cashier

Cashier Hosted Payment Page.

Create a Cashier

Create a Cashier Hosted Payments Page session and pass through all the required information, like the amount, currency, country and reference.

Request
Security:
Request Body schema: application/json
balance
number >= 0

The current available balance of the consumer, if not present, the balance indicator will be hidden.

amount
number >= 0

Allows pre-setting a value on the deposit amount field in the Cashier.

preset_amounts
Array of numbers [ 1 .. 3 ] items

Customize the available preset amounts that will be presented on the deposit screen.

currency
string 3 characters

The 3 characters (string) or 3 digits (code) of the currency in ISO 4217 format, e.g. use USD or 240 for US dollars.

descriptor
string <= 25 characters

A description of the payment, to be displayed in the cardholder’s statement, in order to identify your business name and transaction.

object

The consumer's details, link to existing consumers will be lookuped up by the id if provided, or the email.

consumer_id
string

Pay.com unique identifier of the user, if provided, consumer object will be ignored.

object

Address details.

webhook_url
string

Set the webhook URL on a specific payment level, where we will send payment status updates to.

object

The Cashier Hosted Payment Page details.

reference
string <= 50 characters

A reference you can later use to identify this payment, such as an order number. (saved, query)

echo
string <= 255 characters

Any value up to 255 chars long will be returned within the response. (not saved, not query)

metadata
object

A set of key-value pairs that you can attach to the payment request. This can be useful for storing additional information in a structured format. (saved, not query)

Responses
201Cashier hosted payment page created
400Bad request - the Pay.com API was unable to process your request
401Unauthorized - authentication failed, check your API key
403Forbidden - no access to the requested consumer or checkout
404Not found - requested consumer or checkout not found
422Unprocessable entity - the Pay.com API has failed to process the request due to invalid data/entity
429Too many requests – Your request has hit a rate limit, please wait for a bit and retry
post/cashier
Request samples
application/json
{
  • "balance": 200,
  • "amount": 120,
  • "preset_amounts": [
    ],
  • "currency": "USD",
  • "descriptor": "Pay.com Payment Services",
  • "consumer": {
    },
  • "consumer_id": "82445909165604864",
  • "billing": {
    },
  • "checkout": {},
  • "reference": "8852241-2021",
  • "echo": "order_id=8852241-2021",
  • "metadata": {
    }
}
Response samples
application/json
{}