Payments API

Initiate and manage payments. Requests authenticate by secret key.

List Payments

Request

GET /payment
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

Response

{
  data: [
    {
      accountLastFour: String,
      address: String,
      amount: Number,
      city: String,
      country: String,
      currency: "USD",
      email: String,
      fee: Number,
      firstName: String,
      id: String,
      lastName: String,
      method: "card" | "ach",
      paymentTime: String,
      phone: String,
      postalCode: String,
      pricing: "absorbed" | "dual" | "surcharge",
      rate: Number,
      state: String,
      status: String,
      tax: Number,
      token: String,
      total: Number
    }
  ],
  metadata: {
    limit: Number,
    page: Number,
    pages: Number,
    total: Number
  }
}

See Read Payment below for field details.

Read Payment

Request

GET /payment/:id
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

Response

{
  data: {
    accountLastFour: String,
    address: String,
    amount: Number,
    city: String,
    country: String,
    currency: "USD",
    email: String,
    fee: Number,
    firstName: String,
    id: String,
    lastName: String,
    method: "card" | "ach",
    paymentTime: String,
    phone: String,
    postalCode: String,
    pricing: "absorbed" | "dual" | "surcharge",
    rate: Number,
    refundable: Number,
    refunds: [
      {
        amount: Number,
        fee: Number,
        id: String,
        rate: Number,
        refundTime: String,
        status: "pending" | "success" | "declined",
        tax: Number,
        total: Number
      }
    ],
    state: String,
    status: String,
    tax: Number,
    token: String,
    total: Number
  }
}

Fields

Status

Void Payment

Cancel an unsettled payment (status created or success). Settled payments must be refunded. Requires an Idempotency-Key.

Request

POST /payment/:id/void
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn
Idempotency-Key: String

Response

{
  data: {
    id: String,
    result: "success" | "error" | "processing",
    detail: String,
    voidTime: String
  }
}

Refund Payment

Partial refunds automatically include their share of fees and tax when applicable. Requires an Idempotency-Key.

Request

POST /payment/:id/refund
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn
Idempotency-Key: String

{
  data: {
    amount: Number
  }
}

Response

{
  data: {
    amount: Number,
    detail: String,
    fee: Number,
    id: String,
    paymentId: String,
    rate: Number,
    result: "success" | "error" | "processing",
    tax: Number,
    total: Number
  }
}

Create Session

Optionally authenticate frontend sessions with the Embedded Payments SDK. Configure amount and other payment attributes. Returns an id to open the frontend modal. Payments must complete within one hour of creating the session.

Request

POST /payment/session
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

{
  data: {
    amount: Number,
    customerReference: String,
    product: String,
    sdkProduct: String
  }
}

Response

{
  data: {
    expiresAt: String
    id: String,
  }
}

New Payment

Initiate a new payment with a token from the Embedded Payments SDK. Requires an Idempotency-Key.

Request

POST /payment
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn
Idempotency-Key: String

{
  data: {
    amount: Number,
    token: String
  }
}

Response

{
  data: {
    amount: Number,
    currency: "USD",
    detail: String,
    fee: Number,
    id: String,
    result: "success" | "declined" | "error" | "processing",
    tax: Number,
    token: String,
    total: Number
  }
}

Delete Token

Delete a stored payment token.

Request

DELETE /token/:token
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

Response

{
  data: {
    token: String,
    status: "deleted"
  }
}

Idempotency

Idempotency allows requests to be repeated without repeating the effect. Idempotency prevents a network fault from charging a payer twice.

New, refund, and void requests require an Idempotency-Key header of 1 to 255 characters. Use a unique key for each unique request. Use the same key to repeat a request after receiving an error.

POST /payment
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn
Idempotency-Key: 4f9c1a52-3b0e-4d8e-9a8f-2f6d3c1e7b10

Errors

{
  errors: [
    {
      status: Number,
      title: String,
      detail: String
    }
  ]
}