Observability API

Create an external payment

POST
https://api.sandbox.primer.io/observability/payments

The Observability API is currently in beta. Please contact support@primer.io for access.

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
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
optional enum

See the payment status table for more information.

statusReason
optional object

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

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

metadata
optional map from strings to any

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
optional enum

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
optional string

A description of the payment, as it would typically appear on a bank statement.

Response

This endpoint return 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
optional enum

See the payment status table for more information.

statusReason
optional object

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

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

metadata
optional map from strings to any

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
optional enum

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
optional string

A description of the payment, as it would typically appear on a bank statement.

POST
/observability/payments
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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": 0,
  "createdAt": "2023-01-01T00:00:00Z",
  "order": {
    "id": "string"
  },
  "paymentMethod": {
    "paymentMethodType": "PAYMENT_CARD"
  }
}'
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "paymentId": "string",
  "currencyCode": "AED",
  "processor": {
    "name": "APAYA",
    "merchantId": "string"
  },
  "amount": 0,
  "createdAt": "2023-01-01T00:00:00Z",
  "order": {
    "id": "string",
    "countryCode": "AW"
  },
  "status": "DECLINED",
  "statusReason": {
    "type": "APPLICATION_ERROR",
    "declineType": "SOFT_DECLINE",
    "code": "ERROR",
    "message": "string"
  },
  "paymentMethod": {
    "paymentMethodType": "PAYMENT_CARD",
    "data": {
      "binData": {
        "network": "AMEX",
        "issuerCountryCode": "AW",
        "issuerName": "string",
        "productUsageType": "string",
        "accountFundingType": "string"
      },
      "first6Digits": "string"
    },
    "threeDSecureAuthentication": {
      "transStatus": "string",
      "transStatusReason": "string",
      "responseCode": "NOT_PERFORMED",
      "challengeIssued": true,
      "protocolVersion": "string",
      "reasonCode": "string",
      "reasonText": "string",
      "eci": "string"
    }
  },
  "metadata": {
    "string": {}
  },
  "paymentType": "FIRST_PAYMENT",
  "descriptor": "string"
}