Observability API (Beta)

Create an external payment

POST

The Observability API is currently in beta.

Please contact our Support Team via our JIRA Service Desk for access to the Beta. If you don’t have access, please contact your account administrator for assistance.

Not yet integrated with Primer and interested in learning more? Contact us.

Creating a payment with the Observability API sends external payments data to Primer to populate Observability Payment Insights dashboards. Payments created through the Payments API will be automatically populated and do not need to be sent in the Observability API.

Create an API key with the observability-payments:write scope.

Each record must be created with a unique paymentId. To update a payment record with new data use the PATCH endpoint.

Request

This endpoint expects an object.
paymentId
stringRequired

The payment ID.

The payment ID must be unique. You can use this unique payment ID to update payment details.

currencyCode
enumRequired

The 3-letter currency code in ISO 4217 format.

e.g. use USD for US dollars.

processor
objectRequired
amount
integerRequired

The amount you would like to charge the customer, in minor units. e.g. for $7, use 700.

Some currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for ¥100, use 100. The minimum amount is 0.

createdAt
datetimeRequired

The payment creation date and time (UTC) in ISO 8601 format.

Cannot be updated in partial updates PATCH.

order
objectRequired
paymentMethod
objectRequired
status
enumOptional
statusReason
objectOptional

Pass more information regarding the payment’s status in this field.

This is especially useful when the status is DECLINED or FAILED.

metadata
map from strings to anyOptional

Additional data to be used throughout the payment lifecycle.

Ad dictionary of key-value pairs where the values can only be strings or integers.

e.g. {"productId": 1001, "merchantId": "88278a"}

paymentType
enumOptional

Payment types, primarily to be used for recurring payments.

Note: If you successfully vault a SINGLE_USE token on payment creation, then there’s no need to set a value for this field and it will be flagged as FIRST_PAYMENT. Otherwise, see the table below for all possible values.

paymentTypeUse case
FIRST_PAYMENTa customer-initiated payment which is the first in a series of recurring payments or subscription, or a card on file scenario.
ECOMMERCEa customer-initiated payment using stored payment details where the cardholder is present.
SUBSCRIPTIONa merchant-initiated payment as part of a series of payments on a fixed schedule and a set amount.
UNSCHEDULEDa merchant-initiated payment using stored payment details with no fixed schedule or amount.
MOTOa merchant-initiated mail order or telephone order payment.
IN_STOREa customer-initiated payment where the customer is physically present in a shop.
descriptor
stringOptional
A description of the payment, as it would typically appear on a bank statement.

Response

This endpoint returns an object
paymentId
string

The payment ID.

The payment ID must be unique. You can use this unique payment ID to update payment details.

currencyCode
enum

The 3-letter currency code in ISO 4217 format.

e.g. use USD for US dollars.

processor
object
amount
integer

The amount you would like to charge the customer, in minor units. e.g. for $7, use 700.

Some currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for ¥100, use 100. The minimum amount is 0.

createdAt
datetime

The payment creation date and time (UTC) in ISO 8601 format.

Cannot be updated in partial updates PATCH.

order
object
paymentMethod
object
status
enumOptional
statusReason
objectOptional

Pass more information regarding the payment’s status in this field.

This is especially useful when the status is DECLINED or FAILED.

metadata
map from strings to anyOptional

Additional data to be used throughout the payment lifecycle.

Ad dictionary of key-value pairs where the values can only be strings or integers.

e.g. {"productId": 1001, "merchantId": "88278a"}

paymentType
enumOptional

Payment types, primarily to be used for recurring payments.

Note: If you successfully vault a SINGLE_USE token on payment creation, then there’s no need to set a value for this field and it will be flagged as FIRST_PAYMENT. Otherwise, see the table below for all possible values.

paymentTypeUse case
FIRST_PAYMENTa customer-initiated payment which is the first in a series of recurring payments or subscription, or a card on file scenario.
ECOMMERCEa customer-initiated payment using stored payment details where the cardholder is present.
SUBSCRIPTIONa merchant-initiated payment as part of a series of payments on a fixed schedule and a set amount.
UNSCHEDULEDa merchant-initiated payment using stored payment details with no fixed schedule or amount.
MOTOa merchant-initiated mail order or telephone order payment.
IN_STOREa customer-initiated payment where the customer is physically present in a shop.
descriptor
stringOptional
A description of the payment, as it would typically appear on a bank statement.
POST
$curl -X POST https://api.sandbox.primer.io/observability/payments \
>     -H "X-API-KEY: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "paymentId": "string",
>  "currencyCode": "AED",
>  "processor": {
>    "name": "APAYA"
>  },
>  "amount": 1,
>  "createdAt": "2024-01-15T09:30:00Z",
>  "order": {
>    "id": "string",
>    "countryCode": "AW"
>  },
>  "paymentMethod": {
>    "paymentMethodType": "PAYMENT_CARD",
>    "data": {
>      "binData": {
>        "network": "AMEX",
>        "issuerCountryCode": "AW"
>      }
>    },
>    "threeDSecureAuthentication": {
>      "responseCode": "NOT_PERFORMED"
>    }
>  },
>  "status": "DECLINED",
>  "statusReason": {
>    "type": "APPLICATION_ERROR",
>    "declineType": "SOFT_DECLINE",
>    "code": "ERROR"
>  },
>  "paymentType": "FIRST_PAYMENT"
>}'
Response
1{
2  "paymentId": "string",
3  "currencyCode": "AED",
4  "processor": {
5    "name": "APAYA"
6  },
7  "amount": 1,
8  "createdAt": "2024-01-15T09:30:00Z",
9  "order": {
10    "id": "string",
11    "countryCode": "AW"
12  },
13  "paymentMethod": {
14    "paymentMethodType": "PAYMENT_CARD",
15    "data": {
16      "binData": {
17        "network": "AMEX",
18        "issuerCountryCode": "AW"
19      }
20    },
21    "threeDSecureAuthentication": {
22      "responseCode": "NOT_PERFORMED"
23    }
24  },
25  "status": "DECLINED",
26  "statusReason": {
27    "type": "APPLICATION_ERROR",
28    "declineType": "SOFT_DECLINE",
29    "code": "ERROR"
30  },
31  "paymentType": "FIRST_PAYMENT"
32}
Built with