Payments & Invoicing

Payments

Payments are transactions where money moves directly, and immediately between two accounts.

Payments have multiple use-cases:

1. Peer-to-Peer (P2P) payments directly between two end users.
2. Invoice payments move funds between a user profile and a business profile which generated an invoice.
3. System payments which facilitate program wide features such as card transaction settlement.

Initiate a peer-to-peer payment

Specify the sender and receiving accounts along with the amount to initiate an intra system payment.

Transaction requests require explicitly including a unique transaction_id for idempotency.

POST /transactions

{
  "amount_coins": 7500,
  "from_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
  "to_address": "tp1vdmq58932q2xxl2hg8qvhhvj8pd2mlydjthp7e",
  "note": "Descriptive message associated with the transaction",
  "transaction_id": "d6ce8c20-846e-4902-b5a9-d05b38f2bbfc"
}

Response:

{
  "amount_coins": 7500,
  "blockchain_transaction_hash": "BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11",
  "created_dt": "2022-01-02T03:04:05.123456-05:00",
  "from": {
    "id": "8772b886-d12b-4439-8fff-bc7bfce237b9",
    "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
    "name": "Example Account Name",
    "account_details": {
      "account_type": "PROFILE_ACCOUNT",
      "id": "7e0259ef-84c1-4112-866d-946894a43fbc",
      "profile_details": {
        "profile_type": "PERSONAL",
        "username": "username-example",
        "full_name": "Example User"
      }
    }
  },
  "from_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
  "id": "d6ce8c20-846e-4902-b5a9-d05b38f2bbfc",
  "note": "Descriptive message associated with the transaction",
  "posted_dt": "2022-01-03T03:04:05.123456-05:00",
  "status": "PENDING",
  "to": {
    "id": "30e573b4-e191-4fa4-95fc-fdaf489387c2",
    "blockchain_address": "tp1vdmq58932q2xxl2hg8qvhhvj8pd2mlydjthp7e",
    "name": "Example Account Name",
    "account_details": {
      "account_type": "PROFILE_ACCOUNT",
      "id": "00cbf794-7cb1-41d9-95af-0f4830077e3b",
      "profile_details": {
        "profile_type": "PERSONAL",
        "username": "example-username",
        "full_name": "User Example"
      }
    }
  },
  "to_address": "tp1vdmq58932q2xxl2hg8qvhhvj8pd2mlydjthp7e",
  "type": "TRANSFER",
  "updated_dt": "2022-01-03T03:04:05.123456-05:00"
}

Invoicing

Invoices allow businesses to affect transactions.

Invoices are generated by business accounts and presented to Figure Pay users via QR code for authorization. By authorizing, the end user successfully completes payment for goods and/or services provided by the business.

Generate an Invoice

Generate an invoice with amount and other relevant metadata. The response will contain information that can be used by our client-side QR code generation library.

Invoice requests allow the option of explicitly including a unique id for idempotency.

POST /invoices

{
  "id": "aafe0357-b4c2-410e-bc25-b6675ac547b3",
  "address": "tp1vdmq58932q2xxl2hg8qvhhvj8pd2mlydjthp7e",
  "amount_coins": 7500,
  "label": "Order #289342"
}

Response:

{
  "id": "aafe0357-b4c2-410e-bc25-b6675ac547b3",
  "account_id": "00cbf794-7cb1-41d9-95af-0f4830077e3b",
  "label": "Order #289342",
  "amount_coins": 7500,
  "status": "PENDING" | "COMPLETE" | "EXPIRED" | "CANCELLED" | "REVERSED",
  "network_fee_coins": 38,
  "net_amount_coins": 7462
}

Retrieve an Invoice

Fetch an invoice from the API to check its status or gather metadata required to re-display its contents and re-generate a QR code.

GET /invoices/:invoice_id

{
  "id": "aafe0357-b4c2-410e-bc25-b6675ac547b3",
  "account_id": "00cbf794-7cb1-41d9-95af-0f4830077e3b",
  "label": "Order #289342",
  "amount_coins": 7500,
  "status": "PENDING" | "COMPLETE" | "EXPIRED" | "CANCELLED" | "REVERSED",
  "network_fee_coins": 38,
  "net_amount_coins": 7462
}

Initiate an invoice payment

Similar to a peer-to-peer payment, specify the paying account and the invoice ID to move funds from a personal account to a business account.

POST /transactions/invoice-payment

{
  "amount_coins": 7500,
  "from_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
  "invoice_id": "aafe0357-b4c2-410e-bc25-b6675ac547b3",
  "note": "Descriptive message associated with the transaction",
  "transaction_id": "1a8f7f2c-775c-429c-be90-c246764e2c4b",
  "affiliate_address": "tp1vdmq58932q2xxl2hg8qvhhvj8pd2mlydjthp7e",
  "affiliate_rate": 0.5
}

Response:

{
  "amount_coins": 7500,
  "blockchain_transaction_hash": "BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11",
  "created_dt": "2022-01-02T03:04:05.123456-05:00",
  "from": {
    "id": "8772b886-d12b-4439-8fff-bc7bfce237b9",
    "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
    "name": "Example Account Name",
    "account_details": {
      "account_type": "PROFILE_ACCOUNT",
      "id": "7e0259ef-84c1-4112-866d-946894a43fbc",
      "profile_details": {
        "profile_type": "PERSONAL",
        "username": "username-example",
        "full_name": "Example User"
      }
    }
  },
  "from_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
  "id": "1a8f7f2c-775c-429c-be90-c246764e2c4b",
  "invoice": {
    "id": "aafe0357-b4c2-410e-bc25-b6675ac547b3",
    "label": "Order #289342",
    "network_fee_coins": 37
  },
  "note": "Order #289342",
  "posted_dt": "2022-01-03T03:04:05.123456-05:00",
  "status": "COMPLETE",
  "to": {
    "id": "30e573b4-e191-4fa4-95fc-fdaf489387c2",
    "blockchain_address": "tp1vdmq58932q2xxl2hg8qvhhvj8pd2mlydjthp7e",
    "name": "Example Account Name",
    "account_details": {
      "account_type": "PROFILE_ACCOUNT",
      "id": "00cbf794-7cb1-41d9-95af-0f4830077e3b",
      "profile_details": {
        "profile_type": "BUSINESS",
        "business_name": "Example Business",
        "business_address": {
          "city": "New York",
          "country": "US",
          "state": "NY",
          "street1": "123 Main St.",
          "street2": "Apt. 2",
          "zip": "10001"
      }
    }
  },
  "to_address": "tp1vdmq58932q2xxl2hg8qvhhvj8pd2mlydjthp7e",
  "type": "TRANSFER",
  "updated_dt": "2022-01-03T03:04:05.123456-05:00"
}