Agreements

An agreement is a digital document a merchant fills in and signs to complete KYC. It collects the identity details, the representatives and the payout bank account Ping needs, and it is signed with an e-signing method.

Use it for any merchant that is not a private individual. Registered companies, associations and clubs all go through an agreement. Private individuals normally verify through account verification instead, and KYC covers why both exist.

Before you start

Ping sets up the agreement templates for your tenant. A template carries the wording, the fields and the signing rules that fit the merchants you onboard, so you can have one template or several. You cannot create a template through the API. Talk to Ping about what your merchants need, and the templates show up on your tenant.

Everything below happens against a merchant that already exists, so create the merchant first and keep its merchant_id.

Create the agreement

POST /api/v1/agreements builds the document but does not send it anywhere yet.

{
  "name": "KYC Example Sports Club",
  "merchant_id": "a3453a44-69bf-47eb-bb1a-ae7b1a6ff51d",
  "agreement_template_id": "324c6215-8382-465d-8263-e087e19dbccc",
  "provider_parameters": {
    "party": {
      "name": "Example Sports Club",
      "identifier": "8020000000",
      "country": "SE",
      "participants": [
        {
          "first_name": "John",
          "last_name": "Doe",
          "email": "[email protected]",
          "country": "SE",
          "delivery_channel": "email",
          "editor": true,
          "signatory": true
        }
      ]
    }
  }
}

You get back the agreement id.

party is the counterpart, meaning the merchant. Send it as an organisation with name, identifier, country and participants, or as a private person with a single participant holding an identifier. Organisation participants need an email, and a person party needs the identifier instead.

Participants are the people who touch the document. editor lets someone fill it in and signatory lets someone sign it, and one person is usually both. delivery_channel decides how they receive it once you publish, and sign_method decides how they sign. In sandbox the only sign method available is standard_esign.

Prefill what you already know

GET /api/v1/agreements/{agreement_id} shows the document as it stands. Under provider_data you get data_fields, each with an id, a name and a has_value flag telling you whether it is filled in.

Fill any of them in yourself so the merchant has less to do:

PUT /api/v1/agreements/{agreement_id}/data_fields

[
  { "id": "12345", "value": "Example Sports Club" },
  { "id": "12346", "value": "Sports club" }
]

Publish it

POST /api/v1/agreements/{agreement_id}/publish

{
  "subject": "Sign your Ping onboarding agreement",
  "message": "Hi John, please review and sign so we can start paying you out."
}

Both fields are required. They become the subject and body of what the participants receive on their delivery_channel. A successful publish returns 204, and the agreement moves from CREATED to PENDING once it is out with the participants.

Linking straight to the agreement

Publishing hands delivery to Ping. If you would rather take the participant to the document from inside your own product, ask for a link:

POST /api/v1/agreements/{agreement_id}/participants/{participant_id}/access_link

You get back an access_link that opens the agreement for that one participant.

The link is valid for six hours. Generate it at the moment the participant is about to use it, and treat it as single use. Do not email it, store it or put it anywhere the participant reads later, because it will usually be dead by the time they get there. Call the endpoint again when they come back.

A participant can only sign through an access link when their sign_method verifies identity, such as swedish_bankid or sms, because the link itself proves nothing about who opened it.

What signing gives you

When the agreement reaches SIGNED, the merchant is approved. Ping sets its status to APPROVED, and you find out through the merchant.status.approved webhook or your tenant's merchant status callback. Payouts can run from that point.