Payments

Payments empower your platform to process and manage financial transactions seamlessly. Each payment represents a customer-initiated transaction that can be charged, refunded, cancelled, or adjusted through our robust API and managed via our Platform Dashboard.

Overview

Purpose

Payments enable your platform to offer a smooth, secure transaction experience to your customers. Whether you’re handling one-time purchases, subscriptions, or invoicing, our system supports various payment flows to meet your business needs.

Benefits

Flexibility:
Customize payment flows using endpoints that let you create payment intents, process charges, and manage refunds or cancellations.
Split payments:

Easily allocate portions of a payment to multiple recipients by using our money split feature, enabling transparent revenue sharing and precise fund distribution.
Control:
Monitor detailed payment statuses, adjust invoices, and manage transaction updates with clear API responses.
Automation:
Real-time webhook notifications ensure your payment data is continuously synchronized with your system.

Timeline

Step-by-step explanation

~ = optional steps

Creating a Payment Intent:

Use our APIs Create payment intent-endpoint to initiate a payment intent. The payment starts in an Initiated-state. The Payment can then be cancelled if needed.

~ Cancelling the Payment:

If you need to cancel a payment—maybe if the order was wrong—it can be done through our APIs Cancel payment-endpoint. The payment needs to be in the InitiatedPayment- or ReservedPayment-state to be cancellable. This will stop the customer from charging the payment and the lifetime of the payment will therefore stop here.

It is currently not possible to cancel an invoice-payment.

Charge immediately:

The payment should be charged immediately, as indicated by the chargeImmediately-property in the payment intent. The payment will be processed right after the user completes our payment form, bypassing the ReservedPayment-status and going straight to ChargedPayment.

Charge later:

The payment will be charged later, as indicated by the chargeImmediately-property being set to false. After the user has finished with our payment form, the status of the payment will change to ReservedPayment and the users bank will then reserve the payment.
~ Cancelling a reserved Payment:

If something went wrong—like the user canceling the order—you can use our endpoint to cancel a ReservedPayment payment. The lifetime of the payment stops here. See Cancelling the Payment above.
Manually charging when ready:

When you are ready to charge the payment—for example when your order has been shipped—call the Charge Payment-endpoint from the API-documentation. This action will notify the bank that the payment is ready to be charged, and the payment status will subsequently update to ChargedPayment.

The chargeImmediately-property has no effect on invoices as the user will transfer the money with KID. An invoice can therefore only go from Initiated to Charged

~ (Invoice only) Adjust the invoice:

When an invoice has not been paid—whether being partially paid or not at all—you can adjust the invoice to a lower amount through our Adjust an invoice-endpoint.
- With a lower or equal amount: If the lower amount is lower than what the user already has paid, the excess will be refunded and the status will be set to ChargedPayment.
- With amount set to zero: If set to zero, the payment will be set to ChargedPayment and if it has been partially paid, the excess will be refunded.
Payment is charged:

When the Payment is charged, in the usual case, means that the Payment has completed its lifetime. The merchant have received the money and end-customer have received their order/service. Still there are a few actions that can still be done:
~ Refunding the payment:

If you need to refund a payment, you have the option to both partially- or fully-refund it. The payment needs to be in a ChargedPayment-state to refund a payment.
- Partially refund:
  
  Partially refunding a payment is exactly as it sounds—you can partially refund it. The status will remain ChargedPayment and the user will receive the money back to the account that made the transaction. See the Partially refund payment-endpoint in our API-documentation.
- Fully refund:
  
  Fully refunding a payment will, of course, refund the payment to the user who made the transaction. See the Fully refund payment-endpoint in our API-documentation.

Step-by-step code examples

~ = optional steps

When a payments status changes, a webhook will always be sent to the Webhook defined in your Webhook-channel as well as the endpoint in your Creating a payment-request. See Webhooks-section for more information.

Creating a Payment Intent:

POST /payments

Use our APIs Create payment intent-endpoint to initiate a payment intent.

Request:

{
  "externalPaymentReferenceID": "your-external-unique-id",
  "environment": "test",
  "paymentGateway": "creditcard",
  "chargeImmediately": true,
  "sellerConnectedAccountID": "cad66277-2a14-4648-aa94-8df9d81a6363",
  "externalObjectIdTag": "your-external-object-id-tag",
  "description": "Online store purchase",
  // The grossAmount-property needs to add up to the moneySplitList-properties
  // amount-property.
  "grossAmount": 1000,
  "currency": "NOK",
  "moneySplitList": [
    {
      "connectedAccountID": "cad66277-2a14-4648-aa94-8df9d81a6363",
      "amount": 500,
      "description": "T-shirt product name",
      "isFee": false,
      "externalID": "t-shirt-product-id"
    },
    {
      "connectedAccountID": "cad66277-2a14-4648-aa94-8df9d81a6363",
      "amount": 250,
      "description": "Pants product name",
      "isFee": false,
      "externalID": "pants-product-id"
    },
    {
      // Your platforms fee account. See the Getting Started-page for more info.
      "connectedAccountID": "00000000-0000-0000-0000-000000000000",
      "amount": 250,
      "description": "Platform fee",
      "isFee": true,
      "externalID": "platform-fee"
    }
  ],
  "customerExternalID": "your-external-customer-id",
  // If the customer already exists, you can omit this customer-property.
  // The customer will be created/updated with this value if present.
  "customer": {
    "name": "John Doe",
    "email": "John.Doe@example.com",
    "mobilePrefix": "+47",
    "mobile": "123123123",
    "customerType": "Individual"
  },
  // This property is optional.
  "webhookSubscriptions": [
    {
      // This is the specific event types that will be listened to, in ADDITION to the
      // catchAll-endpoint defined in the Platform Dashboard.
      "eventType": "Charged",
      "url": "https://example.com/webhook/payment-charged"
    }
  ],
  "successUrl": "https://your-system.com/payment/success",
  "failedUrl": "https://your-system.com/payment/failed",

  // If you want to store more information on a payment, you may use the 
  // metaData-property to store this in our system. We do not use this
  // property for anything——it is merely for your system.
  "metaData": {
    "key1": "example",
    "key2": 123,
    "key3": true,
    "key4": null
  }
}

Response:

{
  "paymentIntent": {
    "paymentCreated": {
      // This paymentReferenceID-property is important and will be used to reference
      // this payment in the other endpoints.
      "paymentReferenceID": "123e4567-e89b-12d3-a456-426614174000",
      "externalPaymentReferenceID": "your-external-unique-id",
      // ...other properties. See our Create payment intent-endpoint for more info.
     },
     "moneySplit": [
      {
        // This splitID-property is used to adjust or partially refund
        // the payment later
        "splitID": 1,
        "paymentReferenceID": "08128b38-3ffe-4cdd-a784-c32d2b773daa",
        "connectedAccountID": "cad66277-2a14-4648-aa94-8df9d81a6363",
        "amount": 500,
        "description": "T-shirt product name",
        "insertTime": "2025-03-14T14:18:59.4625281Z",
        "externalID": "t-shirt-product-id",
        "isFee": false
      },
      {
        "splitID": 2,
        "paymentReferenceID": "08128b38-3ffe-4cdd-a784-c32d2b773daa",
        "connectedAccountID": "cad66277-2a14-4648-aa94-8df9d81a6363",
        "amount": 250,
        "description": "Pants product name",
        "insertTime": "2025-03-14T14:18:59.4625283Z",
        "externalID": "pants-product-id",
        "isFee": false
      },
      {
        "splitID": 3,
        "paymentReferenceID": "08128b38-3ffe-4cdd-a784-c32d2b773daa",
        "connectedAccountID": "00000000-0000-0000-0000-000000000000",
        "amount": 250,
        "description": "Platform fee",
        "insertTime": "2025-03-14T14:18:59.4625285Z",
        "externalID": "platform-fee",
        "isFee": true
      }
    ],
   // ...other properties.
}

A webhook will be sent to the catchAll endpoint defined in the Platform-dashboard, as well as to the appropriate webhookSubscriptions-properties “eventType”-url, if defined. See Webhooks-section.

~ Cancelling the Payment:

POST /payments/{paymentReferenceID}/cancel

If you need to cancel a payment it can be done through our APIs Cancel payment-endpoint. The payment needs to be in the InitiatedPayment- or ReservedPayment-state to be cancellable.

Note: Use the statusCode returned from the API instead of the “success“-property

It is currently not possible to cancel an invoice-payment.

Request: No Body

Response:

{
  "response": "…",
  "success": true,
  "error": "…"
}

~ Charging a Payment:

POST /payments/{paymentReferenceID}/charge

This is only available if the payment has it’s chargeImmediately-property set to false. The payment will be charged when this endpoint is called.

Note: Use the statusCode returned from the API instead of the “success“-property

Request: No body

Response:

{
  "success": true,
  "error": "…"
}

A webhook for payment will be sent. See Webhooks-section.

~ (Invoice only) Adjust the invoice:

When an invoice has not been fully paid, you can adjust the invoice to a lower amount through our Adjust an invoice-endpoint.

{
  "moneySplitPatch": [
    // We update the T-shirt product-amount from 500øre (5 NOK) to 250øre (2.5 NOK)
    {
      "splitID": 1,
      "updateType": "UpdateAmount",
      "newAmount": 250
    },
    // We want to delete the pants product, we use the splitID-property
    // from the Create Payment intent-response. The total amount is now
    // reduced by 250øre (2.5 NOK).
    {
      "splitID": 2,
      "updateType": "DoDeleteSplitEntry",
      "doDelete": true
    },
    // We do nothing about the platform fee of 250øre (2.5 NOK)
    {
      "splitID": 3,
      "updateType": "DoNothing"
    }
  ],
  // This is the new gross amount of the payment, this must be
  // the sum of the new moneySplit updated from the moneySplitPatch-list
  "newGrossAmount": 500
}

Payment is charged:

The payment is now charged. And, hopefully, the payments lifetime is complete.

~ Refunding the payment partially:

POST /payments/{paymentReferenceID}/refund/partially

Refunding the payement partially is like adjusting an invoice, the only difference is that the payments status is ChargedPayment .

Request:

{
  "moneySplitPatch": [
    {
      "splitID": 1,
      "updateType": "UpdateAmount",
      "newAmount": 250
    },
    {
      "splitID": 2,
      "updateType": "DoDeleteSplitEntry",
      "doDelete": true
    },
    {
      "splitID": 3,
      "updateType": "DoNothing"
    }
  ],
  "newGrossAmount": 500
}

Response:

{
  "splitList": [
    {
      "splitID": 1,
      "paymentReferenceID": "08128b38-3ffe-4cdd-a784-c32d2b773daa",
      "connectedAccountID": "cad66277-2a14-4648-aa94-8df9d81a6363",
      "amount": 250,
      "description": "T-shirt product name",
      "insertTime": "2023-10-01T12:00:00Z",
      "externalID": "t-shirt-product-id",
      "isFee": false
    },
    {
      "splitID": 3,
      "paymentReferenceID": "08128b38-3ffe-4cdd-a784-c32d2b773daa",
      "connectedAccountID": "00000000-0000-0000-0000-000000000000",
      "amount": 250,
      "description": "Platform fee",
      "insertTime": "2025-03-14T14:18:59.4625285Z",
      "externalID": "platform-fee",
      "isFee": true
    }
  ],
  "refundedSplit": [
    {
      "refundAmount": 250,
      "connectedAccountID": "cad66277-2a14-4648-aa94-8df9d81a6363",
      "description": "Pants product name",
      "externalID": "pants-product-id",
      "isFee": false
    }
  ],
  "message": "…",
  "success": true
}

~ Fully refunding the payment:

POST /payments/{paymentReferenceID}/refund

Note: Use the statusCode returned from the API instead of the “success“-property

Request: No Body

Response:

{
  "response": "…",
  "success": true,
  "error": "…"
}

Keeping in Sync

Our system uses webhook notifications to keep your payment data updated in real time. Whenever a payment is processed, updated, or refunded, webhook events are sent to your configured endpoints in the Platform Dashboard. This automatic synchronization ensures that your platform maintains accurate and current financial records without the need for manual intervention.

See the Payments-section under Webhooks.

Payments

Summary

Creation & Management:
Seamlessly create, process, cancel, and refund payments through dedicated API endpoints.
Flexibility:
Our API supports diverse payment flows—from instant charging to reserved payments and partial refunds—allowing you to tailor transaction processes to your specific business requirements.
Integration:
With clear API models and real-time webhook updates, integrating our Payments API into your platform is straightforward, delivering a robust financial experience for both merchants and customers.

This page serves as a comprehensive guide to understanding and integrating our Payments API. For more detailed information, please refer to our full API documentation or contact API Support at support@kredd.it.