Skip to main content
Payment Status Update
curl --request POST \
  --url https://api.sandbox.primer.io/payment-status \
  --header 'Content-Type: application/json' \
  --header 'X-Signature-Primary: <x-signature-primary>' \
  --header 'X-Signature-Secondary: <x-signature-secondary>' \
  --data '{
  "eventType": "<string>",
  "date": "2023-11-07T05:31:56Z",
  "notificationConfig": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "description": "<string>"
  },
  "version": "2.2",
  "payment": {
    "id": "<string>",
    "date": "2023-11-07T05:31:56Z",
    "status": "PENDING",
    "orderId": "<string>",
    "currencyCode": "<string>",
    "amount": 1,
    "customerId": "<string>",
    "metadata": {},
    "processorData": {},
    "customer": {
      "emailAddress": "jsmith@example.com",
      "mobileNumber": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "billingAddress": {
        "firstName": "<string>",
        "lastName": "<string>",
        "addressLine1": "<string>",
        "addressLine2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "countryCode": "AW",
        "postalCode": "<string>"
      },
      "shippingAddress": {
        "firstName": "<string>",
        "lastName": "<string>",
        "addressLine1": "<string>",
        "addressLine2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "countryCode": "AW",
        "postalCode": "<string>"
      },
      "taxId": "<string>",
      "nationalDocumentId": "<string>"
    },
    "paymentMethod": {
      "descriptor": "<string>",
      "paymentType": "FIRST_PAYMENT",
      "paymentMethodToken": "<string>",
      "isVaulted": true,
      "analyticsId": "<string>",
      "paymentMethodType": "<string>",
      "paymentMethodData": {
        "first6Digits": "<string>",
        "last4Digits": "<string>",
        "expirationMonth": "<string>",
        "expirationYear": "<string>",
        "cardholderName": "<string>",
        "network": "<string>",
        "isNetworkTokenized": false,
        "binData": {
          "network": "AMEX",
          "issuerCountryCode": "AW",
          "issuerName": "<string>",
          "issuerCurrencyCode": "AED",
          "regionalRestriction": "DOMESTIC_USE_ONLY",
          "accountNumberType": "PRIMARY_ACCOUNT_NUMBER",
          "accountFundingType": "CREDIT",
          "prepaidReloadableIndicator": "RELOADABLE",
          "productUsageType": "CONSUMER",
          "productCode": "<string>",
          "productName": "<string>"
        }
      },
      "threeDSecureAuthentication": {
        "responseCode": "NOT_PERFORMED",
        "reasonCode": "GATEWAY_UNAVAILABLE",
        "reasonText": "<string>",
        "protocolVersion": "<string>",
        "challengeIssued": true
      }
    },
    "processor": {
      "name": "<string>",
      "processorMerchantId": "<string>",
      "amountCaptured": 123,
      "amountRefunded": 123
    },
    "statusReason": {
      "type": "APPLICATION_ERROR",
      "declineType": "SOFT_DECLINE",
      "code": "ERROR",
      "message": "<string>"
    },
    "transactions": [
      {
        "transactionType": "SALE",
        "processorTransactionId": "<string>",
        "processorName": "<string>",
        "processorMerchantId": "<string>",
        "processorStatus": "PENDING",
        "processorStatusReason": {
          "type": "APPLICATION_ERROR",
          "declineType": "SOFT_DECLINE",
          "code": "ERROR",
          "message": "<string>"
        },
        "reason": "Item returned."
      }
    ],
    "riskData": {
      "fraudChecks": {
        "source": "FRAUD_PROVIDER",
        "preAuthorizationResult": "THREE_DS",
        "postAuthorizationResult": "ACCEPT"
      },
      "cvvCheck": {
        "source": "PROCESSOR",
        "result": "MATCHED"
      },
      "avsCheck": {
        "source": "PROCESSOR",
        "result": {
          "streetAddress": "NOT_MATCHED",
          "postalCode": "NOT_VERIFIED"
        }
      }
    }
  }
}'
Example payment status notification:
JSON
{
  "eventType": "PAYMENT.STATUS",
  "date": "2021-02-21T15:36:16.367687",
  "notificationConfig": {
    "id": "cc51f9f0-7e1c-492b-9d37-f83a818f6070",
    "description": "Payment webhook"
  },
  "version": "2.2",
  "signedAt": "1689221338",
  "payment": {
    "id": "DdRZ6YY0",
    "date": "2021-02-21T15:34:16.367687",
    "dateUpdated": "2021-02-21T15:35:16.133701",
    "amount": 3000,
    "currencyCode": "GBP",
    "customerId": "cust-123",
    "orderId": "order-123",
    "status": "SETTLED",
    "cardTokenType": "CARD_PAN",
    "customer": {
      "emailAddress": "test@primer.io",
      "mobileNumber": "0123456789",
      "billingAddress": {
        "firstName": "John",
        "postalCode": "CB94BQ",
        "addressLine1": "10001 Alpha St",
        "countryCode": "GB",
        "city": "Cambridge",
        "state": "Cambridgeshire"
      }
    },
    "paymentMethod": {
      "paymentType": "FIRST_PAYMENT",
      "paymentMethodToken": "-lcWjvBAAs2DnIRXwxNjUzNTYzNjIy",
      "isVaulted": "false",
      "analyticsId": "LUi5pETUaVsdSEamK25L",
      "paymentMethodType": "PAYMENT_CARD",
      "paymentMethodData": {
        "last4Digits": "1111",
        "first6Digits": "411111",
        "expirationMonth": "03",
        "expirationYear": "2030",
        "cardholderName": "ADYEN",
        "network": "Visa",
        "isNetworkTokenized": false,
        "binData": {
          "network": "VISA",
          "issuerCountryCode": "US",
          "issuerName": "JPMORGAN CHASE BANK, N.A.",
          "regionalRestriction": "UNKNOWN",
          "accountNumberType": "UNKNOWN",
          "accountFundingType": "UNKNOWN",
          "prepaidReloadableIndicator": "NOT_APPLICABLE",
          "productUsageType": "UNKNOWN",
          "productCode": "UNKNOWN",
          "productName": "UNKNOWN"
        }
      },
      "authorizationType": "FINAL",
      "threeDSecureAuthentication": {
        "responseCode": "NOT_PERFORMED"
      }
    },
    "processor": {
      "name": "STRIPE",
      "processorMerchantId": "acct_1GORasdasqNWFwi8c",
      "amountCaptured": 3000,
      "amountRefunded": 0
    },
    "transactions": [
      {
        "date": "2021-02-21T15:34:16.367687",
        "amount": 3000,
        "currencyCode": "GBP",
        "transactionType": "SALE",
        "orderId": "order-123",
        "processorTransactionId": "pi_3L3edsGZasdasdc1iget38p",
        "processorName": "STRIPE",
        "processorMerchantId": "acct_1GORasvasdNWFwi8c",
        "processorStatus": "SETTLED",
        "cardTokenType": "CARD_PAN"
      }
    ],
    "riskData": {
      "fraudChecks": {
        "source": "riskified",
        "preAuthorizationResult": "THREE_DS",
        "postAuthorizationResult": "ACCEPT"
      },
      "cvvCheck": {
        "source": "processor",
        "result": "MATCHED"
      },
      "avsCheck": {
        "source": "processor",
        "result": {
          "streetAddress": "NOT_MATCHED",
          "postalCode": "NOT_VERIFIED"
        }
      }
    },
    "processorData": {
      "external_ids": {
        "authorization_id": "54B297038E2016701"
      }
    }
  }
}
Learn more about how Primer handles webhooks.

Headers

​
X-Signature-Primary
string
required

An HMAC signature generated using the webhook payload and a shared signing secret. This is then converted to a base64 encoded string.

​
X-Signature-Secondary
string
required

A secondary signature that is added when you have rotated your secret within the past 24 hours.

Body

application/json
​
eventType
string

The type of the webhook raised. PAYMENT.STATUS in this case.

​
date
string<date-time>

The date-time that the webhook was sent.

​
notificationConfig
object

The notification configuration details.

​
version
string

The payload version

Example:

"2.2"

​
payment
object

Response

200

Return a 200 status to indicate that the data was received successfully