Deposit References API Guideline

Endpoints Overview

1. Get All Deposit References

Endpoint: GET /deposit_references
Description: Retrieves all deposit references for a tenant. You can filter the results using the has_unmatched_transfers query parameter to fetch only deposit references with unmatched transfers.

Query Parameters:
- has_unmatched_transfers (optional): Set to true to filter for deposit references with unmatched transfers.

Example Request:

curl -X GET "https://sandbox.pingpayments.com/payments/api/v1/deposit_references?has_unmatched_transfers=true" \
  -H "tenant_id: {tenant_id}" \
  -H "x-api-secret: {api_secret}"

Example Response:

{
  "data": [
    {
      "id": "68a6a036-68e4-44f4-a96f-4c95bec59d0e",
      "reference": "100000793",
      "reference_type": "OCR",
      "purpose": "payment"
    },
    {
      "id": "d6c88a67-0fa8-4e81-a35a-09ac68271b0d",
      "reference": "100000694",
      "reference_type": "OCR",
      "purpose": "payment"
    }
  ],
  "_links": {
    "first": {
      "href": "https://sandbox.pingpayments.com/payments/api/v1/deposit_references?"
    },
    "next": {
      "href": null
    },
    "current": {
      "href": "https://sandbox.pingpayments.com/payments/api/v1/deposit_references?"
    },
    "previous": {
      "href": null
    }
  }
}

2. Get One Deposit Reference

Endpoint: GET /deposit_references/{deposit_reference_id}
Description: Retrieves details of a specific deposit reference, including all bank transfers associated with it.

Example Request:

curl -X GET "https://sandbox.pingpayments.com/payments/api/v1/deposit_references/68a6a036-68e4-44f4-a96f-4c95bec59d0e" \
  -H "tenant_id: {tenant_id}" \
  -H "x-api-secret: {api_secret}"

Example Response:

{
  "id": "68a6a036-68e4-44f4-a96f-4c95bec59d0e",
  "reference": "100000793",
  "reference_type": "OCR",
  "purpose": "payment",
  "transfers": [
    {
      "id": "0365a2e5-1a12-48b7-b5ae-3e9629990884",
      "currency": "SEK",
      "attachments": [],
      "amount": 1000,
      "remittance_information": {
        "reference": "100000793",
        "payment_channel": "bankgirot",
        "payer_information": {
          "name": null,
          "country": null,
          "city": null,
          "postal_code": null,
          "street_address": null
        }
      },
      "value_date": "2024-09-09",
      "booking_date": "2024-09-09",
      "connections": []
    },
    {
      "id": "d76825c0-14ef-403d-9e4b-f9d3f7c0a631",
      "currency": "SEK",
      "attachments": [],
      "amount": 1000,
      "remittance_information": {
        "reference": "100000793",
        "payment_channel": "bankgirot",
        "payer_information": {
          "name": null,
          "country": null,
          "city": null,
          "postal_code": null,
          "street_address": null
        }
      },
      "value_date": "2024-09-06",
      "booking_date": "2024-09-06",
      "connections": [
        {
          "payment_id": "83781718-0103-40f4-9a12-195fe830a26d",
          "connected_by": "Admin",
          "connected_at": "2024-09-06T12:02:52.986843Z",
          "manually_connected": true
        }
      ]
    }
  ],
  "liquidity_account_id": null,
  "payment_ids": [
    "83781718-0103-40f4-9a12-195fe830a26d",
    "ea839a90-4643-4287-afe6-5e45f34d4716"
  ]
}

3. Connect Transfer to Payment

Endpoint: POST /deposit_references/{deposit_reference_id}/transfers/{transfer_id}/connect
Description: Connect an unmatched transfer to a non-funded payment.

Request Parameters:

deposit_reference_id: The ID of the deposit reference.
transfer_id: The ID of the unmatched transfer.
Body Parameters:
- payment_id: The ID of the payment to connect the transfer to.

Example Request:

curl -X POST "https://sandbox.pingpayments.com/payments/api/v1/deposit_references/68a6a036-68e4-44f4-a96f-4c95bec59d0e/transfers/0365a2e5-1a12-48b7-b5ae-3e9629990884/connect" \
  -H "tenant_id: {tenant_id}" \
  -H "x-api-secret: {api_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "ea839a90-4643-4287-afe6-5e45f34d4716",
    "connected_by": "Admin"
  }'

Example Response:

204 No Content

Callback Registration

A callback can be registered to notify your system when a new unmatched transfer is received. To register the callback URL, update your tenant settings.

Register Callback URL

Endpoint: PUT /tenant
Description: Register or update the deposit_reference_callback_url to receive notifications for unmatched transfers.

Example Request:

curl -X PUT "https://sandbox.pingpayments.com/payments/api/v1/tenant" \
  -H "tenant_id: {tenant_id}" \
  -H "x-api-secret: {api_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "deposit_reference_callback_url": "https://yourapp.com/callback/deposit_reference"
  }'

Callback Payload Example:

When a new unmatched transfer is received, the system will send a POST request to the registered callback URL.

Example Callback Payload:

{
  "deposit_reference": {
    "id": "68a6a036-68e4-44f4-a96f-4c95bec59d0e",
    "reference": "100000793",
    "reference_type": "OCR",
    "purpose": "payment"
  },
  "transfer": {
    "id": "ba79ab30-16a2-4136-8093-c35508aaa737",
    "amount": 1000,
    "currency": "SEK",
    "value_date": "2024-09-10",
    "booking_date": "2024-09-10",
    "remittance_information": {
      "reference": "100000793",
      "payment_channel": "bankgirot",
      "payer_information": {
        "name": null,
        "postal_code": null,
        "street_address": null,
        "city": null,
        "country": null
      }
    },
    "connections": [],
    "attachments": []
  }
}

Recommended Workflow

Register a Callback URL:
First, register a callback URL by calling PUT /tenant. This will ensure that your system is notified whenever a new unmatched transfer is received.

curl -X PUT "https://sandbox.pingpayments.com/payments/api/v1/tenant" \
  -H "tenant_id: {tenant_id}" \
  -H "x-api-secret: {api_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "deposit_reference_callback_url": "https://yourapp.com/callback/deposit_reference"
  }'

Handle callback notification:

When you receive a callback notification, create a new payment using the same reference as the transfer.

Example callback payload:

{
  "deposit_reference": {
    "id": "68a6a036-68e4-44f4-a96f-4c95bec59d0e",
    "reference": "100000793",
    "reference_type": "OCR",
    "purpose": "payment"
  },
  "transfer": {
    "id": "ba79ab30-16a2-4136-8093-c35508aaa737",
    "amount": 1000,
    "currency": "SEK",
    "value_date": "2024-09-10",
    "booking_date": "2024-09-10",
    "remittance_information": {
      "reference": "100000793",
      "payment_channel": "bankgirot",
      "payer_information": {
        "name": null,
        "postal_code": null,
        "street_address": null,
        "city": null,
        "country": null
      }
    },
    "connections": [],
    "attachments": []
  }
}

You can now create a payment with the amount and reference provided by calling POST /payment_orders/{payment_order_id}/payments.

Example payment request:

curl -X POST "https://sandbox.pingpayments.com/payments/api/v1/payment_order/{payment_order_id}/payments" \
  -H "tenant_id: {tenant_id}" \
  -H "x-api-secret: {api_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "SEK",
    "method": "deposit",
    "provider": "ping",
    "total_amount": 1000,
    "order_items": [
      {
        "amount": 1000,
        "merchant_id": "{merchant_id}",
        "name": "Item 1",
        "vat_rate": 25
      }
    ],
    "provider_method_parameters": {
      "complete_when_funded": true,
      "reference_type": "OCR",
      "reference": "100000793"
    }
  }'

Example response

{
  "id": "aada68bd-0b48-4aff-bfc1-54ee9d375df3",
  "provider_method_response": {
    "reference": "100000793",
    "deposit_reference_id": "68a6a036-68e4-44f4-a96f-4c95bec59d0e",
    "deposit_account": {
      "bic": null,
      "bban": null,
      "iban": "SE10923102301922039",
      "bankgiro_number": null
    },
    "bank_account": {
      "bic": null,
      "bban": null,
      "iban": "SE10923102301922039",
      "bankgiro_number": null
    },
    "invoice": {
      "display_url": null,
      "download_url": null
    }
  }
}

Connect the Transfer:
After creating the payment, connect the unmatched transfer to the payment by calling POST /deposit_references/{deposit_reference_id}/transfers/{transfer_id}/connect.

curl -X POST "https://sandbox.pingpayments.com/payments/api/v1/deposit_references/68a6a036-68e4-44f4-a96f-4c95bec59d0e/transfers/ba79ab30-16a2-4136-8093-c35508aaa737/connect" \
  -H "tenant_id: {tenant_id}" \
  -H "x-api-secret: {api_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "aada68bd-0b48-4aff-bfc1-54ee9d375df3"
  }'

By following this process, tenants can efficiently handle unmatched transfers and ensure payments are correctly funded.