Observability API

Update an external payment

PATCH

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

You can update payments created earlier through the Observability API with this endpoint. The only required field for the request is paymentId. Other supported request fields are the same as for the create an external payment API call.

If you wish to update nested fields on the payment, you only need to pass the fields that you wish to update. For example to update the processor name, you would pass in processor.name only.

The response will contain all the fields of the payment including the ones that were changed.

Path parameters

paymentIdstringRequired

Request

This endpoint expects an object.
paymentId
stringOptional

The payment ID.

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

currencyCode
enumOptional

The 3-letter currency code in ISO 4217 format.

e.g. use USD for US dollars.

processor
objectOptional
amount
integerOptional

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
datetimeOptional

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

Cannot be updated in partial updates PATCH.

order
objectOptional
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.

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