Payments

8 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

Create a payment

POST/v1/payments

Routes and charges. Amounts are integer minor units. The outcome is final only once the status is terminal (webhook or sync); a timeout is never a decline: retry with the SAME Idempotency-Key.

Authentication: API key (Bearer)
Permission: payment:create
Idempotency-Key: Required
Success: 200

Headers

Idempotency-Keystringrequired
Unique per logical operation: 8-255 characters of A-Z a-z 0-9 _ - : . Retrying with the same key returns the original result and never repeats the side effect; derive it from your own order/payment id.
min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

storeIdstring · uuidrequired
amountintegerrequired
greater than 0
currencystringrequired
3 chars
orderIdstring · uuid
customerIdstring · uuid
emailstring · email
returnUrlstring · uri
captureMethodstring
One ofautomaticmanual
paymentMethodone ofrequired
3 variants (one of)
type: "hosted_fields"
typestringrequired
Alwayshosted_fields
clientTokenstringrequired
min 1 chars
type: "stored_token"
typestringrequired
Alwaysstored_token
tokenstringrequired
min 1 chars
offSessionbooleanrequired
type: "deferred"
typestringrequired
Alwaysdeferred
saveForFutureUseboolean
countrystring
2 chars
billingCountrystring
2 chars
cardBrandstring
max 40 chars
processorAccountIdstring · uuid
customerIpstring
max 64 chars
cardBinstring
pattern ^\d{6,8}$
cardLast4string
pattern ^\d{4}$
cardExpMonthstring
pattern ^\d{1,2}$
cardExpYearstring
pattern ^(\d{2}|\d{4})$
cardFingerprintstring
min 1 chars · max 128 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsPayment

idstring · uuidrequired
objectstringrequired
Alwayspayment
statusstringrequired
amountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
capturedAmountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
storeIdstring · uuidrequired
orderIdstring · uuidrequirednullable
processorAccountIdstring · uuidrequirednullable
nextActionone ofrequirednullable
2 variants (one of)
type: "redirect"
typestringrequired
Alwaysredirect
urlstringrequired
type: "client_secret"
typestringrequired
Alwaysclient_secret
clientSecretstringrequired
cardobjectrequirednullable
Fields: 2 fields
- brandstringrequirednullable
- last4stringrequirednullable
needsReviewbooleanrequired
routingmap<string, any>requirednullable
createdAtstringrequired

Request · cURL

curl -X POST "$GIEP_API_URL/v1/payments" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-pay-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "amount": 4999,
  "currency": "USD",
  "paymentMethod": {
    "type": "hosted_fields",
    "clientToken": "string"
  }
}'

{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "object": "payment",
  "status": "succeeded",
  "amount": {
    "amount": 4999,
    "currency": "USD"
  },
  "capturedAmount": {
    "amount": 4999,
    "currency": "USD"
  },
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "orderId": "f6d8263a-f9f3-46d4-addf-b7d26ffc",
  "processorAccountId": "6a56728f-88e7-43cd-a890-8c9c7d0a",
  "nextAction": {
    "type": "redirect",
    "url": "https://shop.example/thanks"
  },
  "card": {
    "brand": "string",
    "last4": "4242"
  },
  "needsReview": false,
  "routing": {},
  "createdAt": "2026-10-26T12:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

One payment: status, amount and captured amount (integer minor units), card brand and last 4, needsReview and the routing decision. A non-terminal status is not an outcome: wait for the webhook or call sync.

Authentication: API key (Bearer)
Permission: payment:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsPayment

idstring · uuidrequired
objectstringrequired
Alwayspayment
statusstringrequired
amountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
capturedAmountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
storeIdstring · uuidrequired
orderIdstring · uuidrequirednullable
processorAccountIdstring · uuidrequirednullable
nextActionone ofrequirednullable
2 variants (one of)
type: "redirect"
typestringrequired
Alwaysredirect
urlstringrequired
type: "client_secret"
typestringrequired
Alwaysclient_secret
clientSecretstringrequired
cardobjectrequirednullable
Fields: 2 fields
- brandstringrequirednullable
- last4stringrequirednullable
needsReviewbooleanrequired
routingmap<string, any>requirednullable
createdAtstringrequired

Request · cURL

curl -X GET "$GIEP_API_URL/v1/payments/4be35607-8fdb-4b13-a40a-31e36-398" \
  -H "Authorization: Bearer $GIEP_API_KEY"

{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "object": "payment",
  "status": "succeeded",
  "amount": {
    "amount": 4999,
    "currency": "USD"
  },
  "capturedAmount": {
    "amount": 4999,
    "currency": "USD"
  },
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "orderId": "f6d8263a-f9f3-46d4-addf-b7d26ffc",
  "processorAccountId": "6a56728f-88e7-43cd-a890-8c9c7d0a",
  "nextAction": {
    "type": "redirect",
    "url": "https://shop.example/thanks"
  },
  "card": {
    "brand": "string",
    "last4": "4242"
  },
  "needsReview": false,
  "routing": {},
  "createdAt": "2026-10-26T12:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

List processor attempts for a payment

GET/v1/payments/{id}/attempts

Every processor attempt of the payment, in order (attempt number, processor account, status, decline code and category, provider reference).

Authentication: API key (Bearer)
Permission: payment:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/payments/4be35607-8fdb-4b13-a40a-31e36-398/attempts" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Capture an authorised payment

POST/v1/payments/{id}/capture

Auth-only then capture. amount defaults to the authorised amount (integer minor units). Never captures twice; a timeout answers 503 capture_unconfirmed and is safe to retry. Audited.

Authentication: API key (Bearer)
Permission: payment:capture
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

amountinteger
greater than 0

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsPayment

idstring · uuidrequired
objectstringrequired
Alwayspayment
statusstringrequired
amountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
capturedAmountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
storeIdstring · uuidrequired
orderIdstring · uuidrequirednullable
processorAccountIdstring · uuidrequirednullable
nextActionone ofrequirednullable
2 variants (one of)
type: "redirect"
typestringrequired
Alwaysredirect
urlstringrequired
type: "client_secret"
typestringrequired
Alwaysclient_secret
clientSecretstringrequired
cardobjectrequirednullable
Fields: 2 fields
- brandstringrequirednullable
- last4stringrequirednullable
needsReviewbooleanrequired
routingmap<string, any>requirednullable
createdAtstringrequired

Request · cURL

curl -X POST "$GIEP_API_URL/v1/payments/4be35607-8fdb-4b13-a40a-31e36-398/capture" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 4999
}'

{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "object": "payment",
  "status": "succeeded",
  "amount": {
    "amount": 4999,
    "currency": "USD"
  },
  "capturedAmount": {
    "amount": 4999,
    "currency": "USD"
  },
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "orderId": "f6d8263a-f9f3-46d4-addf-b7d26ffc",
  "processorAccountId": "6a56728f-88e7-43cd-a890-8c9c7d0a",
  "nextAction": {
    "type": "redirect",
    "url": "https://shop.example/thanks"
  },
  "card": {
    "brand": "string",
    "last4": "4242"
  },
  "needsReview": false,
  "routing": {},
  "createdAt": "2026-10-26T12:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Reprocess a failed payment as a new attempt

POST/v1/payments/{id}/reprocess

Only a payment that definitively failed with a retryable decline (or that no processor received) and whose card can be charged again without the customer (a reusable token). Never for succeeded, unknown, in-flight or refunded payments, or when the order or checkout was paid another way. Routing runs again; processorAccountId forces one account (needs routing:override, still subject to eligibility and caps: 422 processor_capped / processor_not_eligible). Audited.

Authentication: API key (Bearer)
Permission: payment:reprocess
Idempotency-Key: Required
Success: 200

Path parameters

idstringrequired

Headers

Idempotency-Keystringrequired
Unique per logical operation: 8-255 characters of A-Z a-z 0-9 _ - : . Retrying with the same key returns the original result and never repeats the side effect; derive it from your own order/payment id.
min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

processorAccountIdstring · uuid

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsPayment

idstring · uuidrequired
objectstringrequired
Alwayspayment
statusstringrequired
amountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
capturedAmountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
storeIdstring · uuidrequired
orderIdstring · uuidrequirednullable
processorAccountIdstring · uuidrequirednullable
nextActionone ofrequirednullable
2 variants (one of)
type: "redirect"
typestringrequired
Alwaysredirect
urlstringrequired
type: "client_secret"
typestringrequired
Alwaysclient_secret
clientSecretstringrequired
cardobjectrequirednullable
Fields: 2 fields
- brandstringrequirednullable
- last4stringrequirednullable
needsReviewbooleanrequired
routingmap<string, any>requirednullable
createdAtstringrequired

Request · cURL

curl -X POST "$GIEP_API_URL/v1/payments/4be35607-8fdb-4b13-a40a-31e36-398/reprocess" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-reprocess-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "processorAccountId": "6a56728f-88e7-43cd-a890-8c9c7d0a"
}'

{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "object": "payment",
  "status": "succeeded",
  "amount": {
    "amount": 4999,
    "currency": "USD"
  },
  "capturedAmount": {
    "amount": 4999,
    "currency": "USD"
  },
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "orderId": "f6d8263a-f9f3-46d4-addf-b7d26ffc",
  "processorAccountId": "6a56728f-88e7-43cd-a890-8c9c7d0a",
  "nextAction": {
    "type": "redirect",
    "url": "https://shop.example/thanks"
  },
  "card": {
    "brand": "string",
    "last4": "4242"
  },
  "needsReview": false,
  "routing": {},
  "createdAt": "2026-10-26T12:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Fetch the payment status from the processor

POST/v1/payments/{id}/sync

Server-side status fetch; resolves an unknown payment. Safe to repeat.

Authentication: API key (Bearer)
Permission: payment:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsPayment

idstring · uuidrequired
objectstringrequired
Alwayspayment
statusstringrequired
amountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
capturedAmountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
storeIdstring · uuidrequired
orderIdstring · uuidrequirednullable
processorAccountIdstring · uuidrequirednullable
nextActionone ofrequirednullable
2 variants (one of)
type: "redirect"
typestringrequired
Alwaysredirect
urlstringrequired
type: "client_secret"
typestringrequired
Alwaysclient_secret
clientSecretstringrequired
cardobjectrequirednullable
Fields: 2 fields
- brandstringrequirednullable
- last4stringrequirednullable
needsReviewbooleanrequired
routingmap<string, any>requirednullable
createdAtstringrequired

Request · cURL

curl -X POST "$GIEP_API_URL/v1/payments/4be35607-8fdb-4b13-a40a-31e36-398/sync" \
  -H "Authorization: Bearer $GIEP_API_KEY"

{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "object": "payment",
  "status": "succeeded",
  "amount": {
    "amount": 4999,
    "currency": "USD"
  },
  "capturedAmount": {
    "amount": 4999,
    "currency": "USD"
  },
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "orderId": "f6d8263a-f9f3-46d4-addf-b7d26ffc",
  "processorAccountId": "6a56728f-88e7-43cd-a890-8c9c7d0a",
  "nextAction": {
    "type": "redirect",
    "url": "https://shop.example/thanks"
  },
  "card": {
    "brand": "string",
    "last4": "4242"
  },
  "needsReview": false,
  "routing": {},
  "createdAt": "2026-10-26T12:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Void an authorised or unconfirmed payment

POST/v1/payments/{id}/void

A captured payment is refunded instead. Audited.

Authentication: API key (Bearer)
Permission: payment:capture
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

reasonstring
max 200 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsPayment

idstring · uuidrequired
objectstringrequired
Alwayspayment
statusstringrequired
amountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
capturedAmountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
storeIdstring · uuidrequired
orderIdstring · uuidrequirednullable
processorAccountIdstring · uuidrequirednullable
nextActionone ofrequirednullable
2 variants (one of)
type: "redirect"
typestringrequired
Alwaysredirect
urlstringrequired
type: "client_secret"
typestringrequired
Alwaysclient_secret
clientSecretstringrequired
cardobjectrequirednullable
Fields: 2 fields
- brandstringrequirednullable
- last4stringrequirednullable
needsReviewbooleanrequired
routingmap<string, any>requirednullable
createdAtstringrequired

Request · cURL

curl -X POST "$GIEP_API_URL/v1/payments/4be35607-8fdb-4b13-a40a-31e36-398/void" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "object": "payment",
  "status": "succeeded",
  "amount": {
    "amount": 4999,
    "currency": "USD"
  },
  "capturedAmount": {
    "amount": 4999,
    "currency": "USD"
  },
  "storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
  "orderId": "f6d8263a-f9f3-46d4-addf-b7d26ffc",
  "processorAccountId": "6a56728f-88e7-43cd-a890-8c9c7d0a",
  "nextAction": {
    "type": "redirect",
    "url": "https://shop.example/thanks"
  },
  "card": {
    "brand": "string",
    "last4": "4242"
  },
  "needsReview": false,
  "routing": {},
  "createdAt": "2026-10-26T12:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Reprocess several failed payments; per-item result

POST/v1/payments/reprocess

Each item carries its own idempotency key and runs on its own (same rules as the single call); one refusal never stops the others.

Authentication: API key (Bearer)
Permission: payment:reprocess
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

itemsarray<object>required
min 1 items · max 100 items
Each item has 2 fields
- paymentIdstring · uuidrequired
- keystringrequired
  min 8 chars · max 255 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/payments/reprocess" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "paymentId": "a7c488a4-4db8-4274-ad74-a9a8-710",
      "key": "string"
    }
  ]
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}