[PRIVY] GENERAL API - COMPLETE v.1.7 15 Maret 2023

(1)

[PRIVY] - GENERAL API

DOCUMENTATION v 1.7

(2)

GENERAL API PRIVY

2 PREFACE

This API Documentation is a set of predefined rules and specifications that a software program can follow to use the services and resources provided by another software program. In other words, API is a kind of communication channel through which two separate programs can communicate with each other and share each other's services and resources. This API Specification Document describes the overall technical design for development, which cover the technical attribute.

This document will form a baseline for the subsequent development activities such as programming, customization, and testing of the application module.

(3)

GENERAL API PRIVY

3 Document Change Control

Version Date Authors Summary of Changes

1.0 09/08/2022 Dewi (Tech Writer Team) Initial

1.1 12/08/2022 Dewi (Tech Writer Team) - Add E-Meterai Parameters

1.2 13/08/2022 Dewi (Tech Writer Team) - Add table list document category

1.3 19/08/2022 Dewi (Tech Writer Team) - Edit parameter sign_process = 1

- Edit responses

1.4 26/08/2022 Dewi (Tech Writer Team)

- Edit detail parameters:

a. Custom_signature_placement = Optional b. Document_file = base64

c. E-Meterai = Object

d. Recipient -> Optional if doc_process = 1 - Take out parameter sign_type

1.5 14/11/2022 Dewi (Tech Writer Team) Update OTP:

1. Waiting OTP = 60 Seconds 2. OTP Expired = 15 minutes

1.6 07/12/2022 Dewi (Tech Writer Team) 1. Add Matrix Combination Registration 2. Add param sign_process 0=Serial

1.7 15/03/2023 Dewi (Tech Writer Team)

1. Update credential: body request.

2. Add bulk signing.

3. Delete status registered.

4. Update type parameter at document signing.

5. Update document status.

(4)

GENERAL API PRIVY

4 Table of Contents

1. Credential ... 5

1.1. Endpoint ... 5

1.2. Credential Development (Different for each Channel) ... 5

2. Generate Signature ... 6

2.1. Body Request ... 6

2.2. Timestamp ... 6

2.3. hmacAsBase64 ... 6

2.4. Signature ... 6

4. Header Message Structure API GATEWAY - PRIVY ... 8

5. Header Message Structure Call-back API GATEWAY - CHANNEL ... 9

6. Channel ID ... 10

7. API Reference Register ... 11

7.1. Register ... 11

7.1.1. Privy as Registration Authority – Full API ... 11

7.1.2. Privy as Registration Authority – Landing Page from Privy ... 11

7.1.3. Merchant as Registration Authority ... 11

7.2. Resend Register ... 16

7.3. Check Registration Status ... 18

8. Upload Document ... 21

8.1. Document Signing with E-Meterai and New User ... 21

8.2. Check Status Document Signing (Redownload Signed Document) ... 34

8.3. Check Document History ... 39

8.4. Revoke by merchant ... 43

8.5. Re-blast ... 44

9. Bulk Signing ... 45

9.1. Request OTP ... 45

9.2. OTP Validation ... 47

10. OTP ... 49

10.1. Request OTP ... 49

10.2. Resend OTP ... 51

10.3. OTP Validation ... 53

11. Call-back ... 55

11.1. Call-back Register ... 55

11.2. Call-back Document Signing ... 58

12. Response Code ... 62

12.1. Reject Reason Registration – Privy as RA ... 62

12.2. Reject Reason Registration – Merchant as RA ... 63

12.3. Reject Reason – Document Signing ... 63

(5)

GENERAL API PRIVY

5 1. Credential

1.1. Endpoint

Development

1.2. Credential Development (Different for each Channel) Username

Password API Key Secret Key

(6)

GENERAL API PRIVY

6 2. Generate Signature

Merchant is equipped with a message signature to maintain the integrity of the message body value. Partners are asked to maintain the confidentiality of the keys.

2.1. Body Request

Body = params.except ("ktp", "identity", "selfie", "supporting_docs",

"document"}

The body above is the request parameters that exclude object KTP, identity, selfie, supporting document and document.

Body request using format Json without using spatial.

body = body.to_json raw_text = body.gsub(“,”)

2.2. Timestamp

Times using format “Time.now.strftime('%Y-%m-%dT%H:%M:%S+07:00')” and Zulu time zone must change to

“Asia/Jakarta” (GMT+7). Value timestamp must be same with Header Timestamp. Example: 2020-08-03T14:58:50+07:00.

2.3. hmacAsBase64

Hash variable timestamp + ":" + apikey + ":" + httpVerb + ":" + bodymd5 (with format "UTF-8") using HMAC with algorithm SHA-256 and API Secret (with format "UTF-8") as a secret key. Encode the result use base64 encode to string.

No Field Name Example Description

1 timestamp 2020-08-03T14:58:50+07:00.

2 api_key api_key from privy Refer to Credential.

3 api_secret api_secret from privy Refer to Credential.

4 httpVerb Post

5 bodymd5

body_md5 = Digest::MD5.base64digest(raw_text)

hmac_signature = timestamp + ":" + api_key + ":" + httpVerb +":" + body_md5

digest = OpenSSL::Digest.new('sha256')

hmac = OpenSSL::HMAC.digest(digest, api_secret, hmac_signature) hmac_base64 = Base64.strict_encode64(hmac)

2.4. Signature

Concatenate API Key with hmacAsBase64 and do base64 encode to string.

auth_string = "{api_key}:{hmac_base64}"

signature = Base64.strict_encode64(auth_string)

(7)

GENERAL API PRIVY

7 3. Authorization

Authorization is using Bearer authentication scheme (token authentication) that involves security tokens called bearer token. Bearer token is a cryptic string, usually generated by the server in response to a login request. For instructions on getting tokens, follow these steps.

a. REQUEST Method: POST

Development {{base_url}}/oauth2/api/v1/token

b. BODY OF REQUEST

Paramater’s Name Type M/O Example Description

client_id String M {{username}} Client’s username.

client_secret String M {{password}} Client’s password.

grant_type String M client_credentials Client’s credentials.

{

"client_id": "{{username}}", "client_secret": "{{password}}", "grant_type": "client_credentials"

}

c. BODY OF RESPONSE

Paramater’s Name Type Example Description

message String Success retrieve data Message of response.

data Object [] Data’s information.

access_token String yJQy3p6oVvDuLztredn3nEug Token generated by system.

token_type String bearer Authorization type.

expires_in String 86400 Status expired.

{

"message": "Success retrieve data", "data": {

"access_token": "yJQy3p6oVvDuLztredn3nEug", "token_type": "bearer",

"expires_in": 86400 }

}

(8)

GENERAL API PRIVY

8 4. Header Message Structure API GATEWAY - PRIVY

Partner should send this request header at HTTP(S) header which contains

No Field Name Type M/O Example Description

1 Content-Type String M application/json

http_form Content of your request body.

e.g.: application/json.

2 Request - ID String M 1234567890123456 Unique identifier request

generated by merchant, format:

16 integers.

3 Timestamp String M 2020-07-10T11:48:13 Timestamp generated by

merchant in ISO 8601 format:

yyyy-MMddTHH:mm:ssZ e.g. “”

4 Signature Date

Time M ZjZlMjE0ZmJmODgyNzM5NDZkNmEzN

TFmNDgxYTFmOTU6NWI1eFFuOE5OZ FJ0d2F

aZlZJaVkyQ3puaFlEcWV4MDNkMUFJU jNCV1U5MD0=,

Signature is used by Merchant to verify

that your request is not altered by attackers.

5 Authorization String M Token

Q0lNQjAyOkdYRE9CTFhXQlFKSkxRWlF VWU9PUkJNVEtJU1ZORlJY

Using bearer authorization.

Sample request header

Content-Type: application/json Request-ID: 1234567890123456, Timestamp: 2020-07-10T11:48:13,

Signature: ZjZlMjE0ZmJmODgyNzM5NDZkNmEzNTFmNDgxYTFmOTU6NWI1eFFuOE5OZFJ0d2F aZlZJaVkyQ3puaFlEcWV4MDNkMUFJUjNCV1U5MD0=,

Authorization: Bearer

Q0lNQjAyOkdYRE9CTFhXQlFKSkxRWlFVWU9PUkJNVEtJU1ZORlJY

(9)

GENERAL API PRIVY

9 5. Header Message Structure Call-back API GATEWAY - CHANNEL

Partner should send this request header at HTTP(S) header which contains

No Field Name Type M/O Example Description

1 Content-Type String M application/json

http_form Content of your request body.

e.g: application/json.

2 Authorization String M Q0lNQjAyOkdYRE9CTFhXQlFKSkxRWlF

VWU9PUkJNVEtJU1ZORlJY Basic auth atau bearer token.

Sample request header

Content-Type: application/json

Authorization: Q0lNQjAyOkdYRE9CTFhXQlFKSkxRWlFVWU9PUkJNVEtJU1ZORlJY

(10)

GENERAL API PRIVY

10 6. Channel ID

Parameter channel_id is the channel to identify product/application for clients. For the channel_id, the default is 001.

Channel ID Application Description

001

(11)

GENERAL API PRIVY

11 7. API Reference Register

7.1. Register a. REQUEST

Method: POST

Development {base_url}}/web/api/v2/register

This API register is used to create new user or user registration using the same endpoint with different case. For details, body request and response will be explained below.

7.1.1. Privy as Registration Authority – Full API

Privy will act as Registration Authority (RA). In this case, Merchant needs to provide all required information for user validation purpose via API, the required information is name, NIK, date of birth, email, phone number, a picture of selfie and a picture of identity (KTP).

7.1.2. Privy as Registration Authority – Landing Page from Privy

Privy will act as Registration Authority (RA). In this request, merchant needs to provide at least user’s email and phone number, and Privy will send a link to user via email / SMS and navigate user to landing page provided by Privy. On the landing page, user can fill the required information such as name, NIK, date of birth, email, phone number, photo of selfie and photo of identity (KTP).

7.1.3. Merchant as Registration Authority

Merchant will act as Registration Authority (RA). In this case, merchant needs to fulfil the requirement as Registration Authority (RA) from Privy side. Merchant will provide all required information: name, NIK, date of birth, email, phone number, photo of selfie and photo of identity (KTP).

Paramater’s Name Type M/O Example Description Max

Length reference_number String M 5 application ID+ 10

running number eg: PRVID0000000001

User’s reference number

generated by client. 32

channel_id String M 001 Refer to list channel ID. Default using 001. 32

info String O randomstring Additional info provides by merchant

email String M dhimas.email@gmail.com User’s email address 32

phone String M 081320210100 User’s phone number 14

nik String M/O 3302185203930001 - User’s ID number.

- Optional if Privy as RA – Landing from Privy.

16

name String M/O Dhimas Pramudya - User’s name EKTP.

100

dob String M/O 1993-03-12 (YYYYMMDD) - User’s date of birthday.

10

selfie File M/O data:image/png;base64,..

.. - User’s Selfie.Format: jpg, jpeg, png.

identity File M/O data:image/png;base64,..

.. - User’s ID image. Format: jpg, jpeg, png.

(12)

GENERAL API PRIVY

12 {

"reference_number": "PRVID0000000001", "channel_id": "001",

"info":"randomstring"

"email": "dhimas.email@gmail.com", "phone": "081320210100",

"nik": "3302185203930001", "name": "Dhimas Pramudya", "dob": "1993-03-12",

"selfie": "data:image/png;base64,....", "identity": "data:image/png;base64,...."

}

c. BODY OF RESPONSE:

1) Privy as RA – Full API

Paramater’s Name Type Example Description Max

Length message String Success retrieve data Message of response.

data Object[] Data information.

reference_number String PRVID0000000001 User’s reference number. 32 channel_id String 001 Refer to list channel ID. Default, using

001. 32

info String randomstring Additional info provides by merchant

register_token String f40a20bb2ac0aac07e3… Token number for register. 16 status String waiting_verification Data’s status. Value:

a) waiting_verification b) registered (new user) c) rejected

20

a) Success {

"info":"randomstring",

"register_token": "f40a20bb2ac0aac07e34351b2a2e5f58s", "status": " waiting_verification"

} }

(13)

GENERAL API PRIVY

13 2) Privy as RA – Landing Page from Privy

data Object[] Data’s information.

reference_ number String PRVID0000000001 User’s reference number. 32

channel_id String 002 Refer to list channel ID.

Default, using 001. 32

info String randomstring Additional info provides by

merchant

register_token String f40a20bb2ac0aac07e3435… Token number for register. 16 registration_url String https://dcid.io/6hsjad URL for registration landing

page. 25

status String pending Data’s status. 20

a) Success {

"reference_number": "PRVID0000000001", "channel_id" : "002",

"info":"randomstring"

"register_token": "f40a20bb2ac0aac07e34351b2a2e5f58s", "registration_url":"https://dcid.io/6hsjad",

"status": "pending"

} }

3) Merchant as Register Authority

Parameter’s Name Type Example Description Max

reference_number String PRVID0000000001 Reference number previously

generated by channel. 32

Default using 001. 32

merchant.

register_token String random token Token number of register. 32

status String verified Register’s status. 20

privy_id String DHIM0472 User’s Privy username. 8

email String dhimas.email@gmail.com User’s email. 32

phone String 62895630369573 User’s phone number. 14

identity Object[] Information of user’s identity.

nama String Dhimas Pramudya User’s name. 100

nik String 3302185203930001 User’s ID number. 16

tanggalLahir Date 1993-03-12 User’s date of birth. 10

(14)

GENERAL API PRIVY

14 a) Success Verified

{

"register_token": "f40a20bb2ac0aac07e34351b2a2e5f58s", "status": "verified",

"privy_id": "DHIM0472",

"identity": {

"nama": "Dhimas Pramudya", "nik": "3302185203930001", "tanggalLahir": "1993-03-12"

} } }

4) Rejected {

"register_token": "c5417457cb14fe06ab5683dc6fc35366", "status": "rejected",

"reject_reason": { "code": "RC18",

"reason": "Email Customer terkait dengan PrivyID terdaftar"

},

"resend": false }

}

5) Invalid Param {

"error": { "code": 422, "errors": [ {

"param": "channel_id", "messages": [

"Channel ID is not registered"

] } ] } }

(15)

GENERAL API PRIVY

15 6) Server Error

{

"error": { "code": 500, "errors": [

"Something went wrong"

] } }

7) Invalid auth {

"401 Unauthorized"

] } }

8) Invalid auth signature {

"401 Invalid signature"

] } }

(16)

GENERAL API PRIVY

16 7.2. Resend Register

a. REQUEST Method: POST

Development {{base_url}}/web/api/v2/register/resend

Length reference_number String M 5 id aplikasi + 10 running

number

eg: PRVID0000000001

User’s reference number

generated by client. 32

channel_id String M 001 Refer to list channel ID. Default using

001. 32

register_token String M 0a87da0ac5eef7c25b78… Token number for register. 32

info String O randomstring Additional info provides by merchant

selfie Image O data:image/jpeg;base64,.... Refer to handle on reject reason.

Use File or Base64

supporting_document Array O Supporting document info.

document_name String M Kartu Keluarga Document name.

document File/Base64 M data:image/jpeg;base64,.... Refer to handle on reject reason.

Use File or Base64 {

"reference_number": "{{reference_number}}", "channel_id": "{{channel_id}}",

"register_token": "{{register_token}}", "info": "randomstring ",

"selfie": "Selfie.jpg”, "supporting_document": [ {

"document_name":"Kartu Keluarga", "document":"base64_data"

} ] }

Parameter’s Name Type Example Description Max

reference_ number String PRVID0000000001 User’s reference number. 32 channel_id String 001 Refer to list channel ID. Default

using 001. 32

info String randomstring Additional info provides by merchant.

register_token String 0a87da0ac5eef7c25b78… Token number for register. 16 registration_url String https://dev.dcid.io/8f5... URL for registration landing page. 25 status String waiting_verification Register status

(17)

GENERAL API PRIVY

17 {

"info": "randomstring ",

"register_token": "0a87da0ac5eef7c25b7835ae6711025a", "registration_url": "https://dev.dcid.io/8f53c", "status": "waiting_verification"

} }

(18)

GENERAL API PRIVY

18 7.3. Check Registration Status

Development {{base_url}}/web/api/v2/register/status

Parameter’s Name Type M/O Example Description Max

Length reference_number String M PRVID0000000001 Reference number previously

001. 32

register_token String M AAAasmQ0lNQjAyOkdYRE9 CTFhXQlFKSkxRWlFVWU9P UkJNVEtJ

Unique identifier to represented user

generated by Privy. 32

info String O randomstring Additional info provides by merchant.

{

"register_token": " AAAasmQ0lNQjAyOkdYRE9CTFhXQlFKSkxRWlFVWU9PUkJNVEtJ"

"info": "randomstring"

}

c. BODY OF RESPONSE 1) Verified

Length

message String M Success retrieve data Message of response.

data Object[] M Data’s information.

reference_number String M PRVID0000000001 Reference number previously

001. 32

info String O randomstring Additional info provides by merchant.

register_token String M 40a20bb2ac0aac07e3435… Token number of register. 32

status String M verified Register’s status. 20

privy_id String M DHIM0472 User’s Privy ID. 8

email String M dhimas.email@gmail.com User’s email. 32

phone String M 62895630369573 User’s phone number. 14

identity Object[] M Information of user’s identity.

nama String M Dhimas Pramudya User’s name. 100

nik String M 3302185203930001 User’s ID number. 16

tanggalLahir Date M 1993-03-12 User’s date of birth. 10

(19)

GENERAL API PRIVY

19 {

"register_token": "f40a20bb2ac0aac07e34351b2a2e5f58s", "status": "verified",

"privy_id": "DHIM0472",

"identity": {

"nama": "Dhimas Pramudya", "nik": "3302185203930001", "tanggalLahir": "1993-03-12"

} } }

2) Rejected

Parameter’s Name Type M/O Example Description Max Length

message String M Success retrieve data Message of response.

data Object[] M Data’s information.

reference_number String M PRVID000000001 Reference number generated

by merchant. 32

channel_id String M 001 Refer to list channel ID.

info String O randomstring Additional info provides by

merchant

register_token String M 9faa79c389b35be0f132d

d9cc5504b63 Token number of register. 32

status String M rejected Register’s status. 20

reject_reason Object[] M Reject reason’s information.

reason String M Nomor HP sudah

terasosiasi dengan Privy lain.

Reject reason’s name.

code String M RC09 Reject reason’s code. 8

resend Boolean M false or true

if true, landing page retry process with supporting document (misalnya Kartu Keluarga) Limitation soft reject (3x soft reject hard reject)

Resend callback.

false = hard reject NIK doesn’t exist in the Dukcapil database.

true = soft reject - Foto Selfie Blur - Foto EKTP blur

(20)

GENERAL API PRIVY

20 {

"register_token": "f40a20bb2ac0aac07e34351b2a2e5f58s", "status": "rejected",

"reject_reason": {

"reason": "Nomor HP sudah terasosiasi dengan Privy lain", "code": "RC09"

},

"resend": false }

3) Invalid Param {

"Channel ID is not registered"

] } ] } }

4) Server Error {

"Something went wrong"

] } }

5) Invalid auth {

"401 Unauthorized"

] } }

6) Invalid auth signature {

] } }

(21)

GENERAL API PRIVY

21 8. Upload Document

8.1. Document Signing with E-Meterai and New User a. REQUEST

Method: POST

Development {{base_url}}/web/api/v2/doc-signing

Length reference_number String M 5 application ID+ 10

running number.

e.g.: PRVID0000000001

User’s reference number generated

by client. 32

channel_id String M 001 Refer to list channel ID.

Default using 001. 32

custom_signature_placement Boolean O True Only used when using X and Y coordinates.

doc_process Integer M 0 Value:

0: Doc signing only 1: Emeterai only

2: Doc signing first, then E-Meterai 3: Emeterai first, then doc signing Note:

Default value: 0.

info String O randomstring Additional info provides by

merchant.

visibility Boolean O true True = sign will be visible in the

document

False = sign will be invisible Note: Used in Latin Signature checking appears.

Default: true Document Owner

doc_owner Object[] M Owner’s information.

privyId String M MDR0101 Privy ID of document owner. 8

enterpriseToken String M Refer to credential Enterprise token of owner. 64 Document To Sign

document Object[] M 1 Document Document’s information

Total size Up to 5 MB.

document_file File M Document.pdf Document’s file.

Format: Using base64.

document_name String M Document’s name.

sign_process String O 0 or 1 1 = Parallel

0 = Serial Recipients

recipients Array[] M/O List of signers Recipient’s information.

If doc_process = 1 -> Optional

user_type String O 0 or 1 0 = internal user,

1 = external user.

Default value : 0

id_user String M DHI0742

or if user_type = 0 -> Privy 16

(22)

GENERAL API PRIVY

22 3275081203771234 if user_type = 1 or New User -> NIK

or phone.

signer_type String M Signer Type of recipients.

enterpriseToken String O Refer to credential Enterprise token of recipients. 64

notify_user String O 0 or 1 Notify User:

0 = Signing link will not be sent to the signer

1 = Signing link will be sent to the signer

drag_n_drop Boolean O true or false If true: placement signature will be able to drag and drop

If false: placement signature will not able to move

detail String O 0 or 1 0 = Signature detail without

timestamp.

1 = Signature detail with timestamp.

posX String O 0 if custom_signature_placement:

true -> Mandatory

if custom_signature_placement:

false -> Optional : Delete when using drag_n_drop

posY String O 0 if custom_signature_placement:

true -> Mandatory

if custom_signature_placement:

false -> Optional : Delete when using drag_n_drop

signPage String O 1 Default value 1

Page for sign.

New User (If the recipients not registered in Privy)

user_data Object M List for new signers If recipient is not registered in privy

name String M New User New user’s name

phone String M 081xxxxxxxxx New user’s phone number

email String M user@gmail.com New user’s email address

dob Date M 2001-01-05 New user’s birthday

selfie String O null Selfie

identity String O null Supporting document: KTP.

E-meterai

e_meterai Object M E-meterai information.

If doc_process = 1/2/3 -> Object parameters is Mandatory doc_category String M Akta Pejabat E-meterai document category.

stamp_position Array M Stamp position detail.

pos_x Float M 70.9489288330078 X Coordinates.

pos_y Float M 678.3644943237305 Y Coordinates.

page Integer M 1 Page for E-meterai.

dimension Integer O 79.43023251 E-meterai dimension.

(23)

GENERAL API PRIVY

23 Document Category

Akta Pejabat Dokumen Lain-lain

Surat Berharga Dokumen pelunasan utang (lebih dari 5 juta)

Dokumen Transaksi Surat Keterangan

Dokumen Lelang Surat Pernyataan

Dokumen pernyataan jumlah uang lebih dari 5 juta. Surat lainnya

Akta Notaris Dokumen penerimaan uang (lebih dari 5 juta)

Surat Perjanjian

1) 1 Signer 1 E-Meterai {

"reference_number": "{{doc_reference_number}}", "channel_id": "{{channel_id}}",

"doc_process": 2, "info": "",

"visibility": true, "doc_owner": {

"privyId": "DCIUAT",

"enterpriseToken": "41bc84b42c8543daf448d893c255be1dbdcc722e"

},

"document": {

"document_file": ",

"document_name": "docsign3", "sign_process": "1",

"barcode_position": "0"

},

"recipients": [ {

"user_type": "0", "id_user": "devan6564", "signer_type": "Signer", "enterpriseToken": "", "notify_user": "1", "drag_n_drop": false, "detail": "0",

"posX": "0", "posY": "0", "signPage": "1"

} ],

"e_meterai": {

"doc_category": "Akta Pejabat", "stamp_position": [

{

"pos_x": 70.9489288330078, "pos_y": 678.3644943237305, "page": 2,

"dimension": 79.43023251 }

] }

}

2) 2 Signer – 1 E-Meterai {

(24)

GENERAL API PRIVY

24 "reference_number": "{{doc_reference_number}}",

"channel_id": "{{channel_id}}", "doc_process": 2,

"info": "",

},

"document": {

"document_file": ",

},

"recipients": [ {

} }, {

} ],

"e_meterai": {

{

"pos_x": 70.9489288330078, "pos_y": 678.3644943237305, "page": 2,

"dimension": 79.43023251 }

] } }

(25)

GENERAL API PRIVY

25 3) 3 Signer, 1 of them Auto Approve – 3 E-Meterai

{

"reference_number": "{{doc_reference_number}}", "channel_id": "{{channel_id}}",

"doc_process": 2, "info": "",

},

"document": {

"document_file": ",

},

"recipients": [ {

}, {

} ],

"e_meterai": {

{

"pos_x": 70.9489288330078, "pos_y": 678.3644943237305, "page": 2,

"dimension": 79.43023251

(26)

GENERAL API PRIVY

26 },

{

"pos_x": 150.9489288330078, "pos_y": 678.3644943237305, "page": 2,

"dimension": 79.43023251 },

{

"pos_x": 250.9489288330078, "pos_y": 678.3644943237305, "page": 2,

"dimension": 79.43023251 }

] } }

4) New User Signer {

"reference_number": "{{reference_number}}", "channel_id": "{{channel_id}}",

"doc_process": 0, "doc_owner": {

"Privy": "DCIUAT",

},

"document": {

"document_file": "data:file/pdf;base64, "document_name": "Test Approve",

"notify_user": "1", "sign_process": "1", "barcode_position": "0"

},

"recipients": [ {

"user_data": {

"name": "Test Nama", "phone": "08114060001",

"email": "1406Test01@gmail.com", "dob": "2001-01-05",

"selfie": null, "identity": null }

} ],

"e_meterai": {

{

"pos_x": 70.9489288330078, "pos_y": 678.3644943237305, "page": 2,

"dimension": 79.43023251

(27)

GENERAL API PRIVY

27 }

] }

}

1. Success Uploaded – 1 Signer

reference_ number String PRVID0000000001 User’s reference number. 32 channel_id String 001 Refer to list channel ID. Default using

001. 32

document_ token String e478cd757de0e7527c2c7

1857cad4310 Token number for document. 32

status String uploaded Document has been uploaded and not

signed yet.

message String success Message info.

signing_url String https://dcid.io/6hsgh URL for signing document. 25 Info String "FexDnnZcSTMO6O7iprX

AQkWptWNRSz0nS….

{

"reference_number": "QATESTDS150323009", "channel_id": "001",

"document_token": "8a9468bd357fb92747bcdcef808a0f59", "status": "uploaded",

"message": "Success",

"signing_url": "https://dev.dcid.io/1c32", "info":

"FexDnnZcSTMO6O7iprXAQkWptWNRSz0nS+Q3b2og09p17Kw5yssG6RPjHsoo9BY7ZPp4/V3R6DyPHLU atKPTzrTgDa7+COLPUstaxCqcWmW+2CXIKLLB9RtfgbKMkQyFIEllsA=="

} }

(28)

GENERAL API PRIVY

28 2. Success Uploaded – More than 1 Signers.

document_ token String e478cd757de0e752… Token number for document. 32

status String uploaded The document has been uploaded and

not signed yet.

signing_urls Object[] List URL for signing document. 25

devan6564 String https://dev.dcid.io/663ca URL for signing document. If more than 1 recipient.

anf2201 String https://dev.dcid.io/baf1d URL for signing document. If more than 1 recipient.

{

"document_token": "addfdbe2526ee26a0f899b6e32963113", "status": "uploaded",

"signing_urls": {

"crj0001": "https://dev.dcid.io/663ca", "devan6564": "https://dev.dcid.io/baf1d"

} } }

3. Processing

channel_id String 001 32

document_ token String e478cd757de0e7527… Token number for document. 32 status String processing Document has been signed by some

signer(s) but not completed yet (not all signers has signed the document).

{

"reference_number": "PRVID0000000001", "channel_id": "001"

"document_token": "aa02582db9bfb9cb23ffcc0da93645e2", "status": "processing",

"message": "Success"

} }

(29)

GENERAL API PRIVY

29 4. Process_emeterai

reference_ number String PRVID0000000001 User’s reference number. 32 channel_id String 001 Refer to list channel ID. Default using

001. 32

document_ token String e478cd757de0e7527c2c7

1857cad4310 Token number for document. 32

status String process_emeterai Document is being process for e-stamp (e-meterai)

signing_url String https://dcid.io/6hsgh URL for signing document. 25

info String 6372DB07CD20ACB4………

…..

{

"document_token": "5e43ec289f196688e9f974920855e41e", "status": "process_emeterai",

"message": "Success", "info":

"6372DB07CD20ACB446B7DABFEC05A3375840CEF2AF0FF4C34102AB5CA3B45E5D81D80F6E2F09F16 3E693E0CABC8E6C62BFF8F6467D7C8BC2F2549987FBBC175D005A7F3769F8B19B2184F16640DAF9B 8E5F346F05F67E75EED2AD6D3EE0822512D8167D6E764348497AC7BB1B512F088"

} }

5. Completed

document_ token String e478cd757de0e7527c2c718… Token number for document. 32

status String completed Document has been signed by all

signers/recipients.

signing_url String https://dcid.io/6hsgh URL for signing document. 25

info String FexDnnZcSTMO6O7iprXAQkWp

tWNR……

(30)

GENERAL API PRIVY

30 {

"document_token": "48569cce0a00065232ace6fb00a451fa", "status": "completed",

"unsigned_document": "data:application/pdf;base64", "signed_document": "data:application/pdf;base64", "info":

"FexDnnZcSTMO6O7iprXAQkWptWNRSz0nS+Q3b2og09p17Kw5yssG6RPjHsoo9BY7ZPp4/V3R6DyPHLU atKPTzrTgDa7+COLPUstaxCqcWmW+2CXIKLLB9RtfgbKMkQyFIEllsA=="

} }

6. Rejected Document

Length reference_number String PRVID0000000001 Reference number previously

channel_id String 001 Refer to list channel ID. 32

info String randomstring Additional info provided by

merchant.

status String rejected Document has been rejected by

signer.

recipient Array List of document recipient

privy_id String AH6000 PrivyID’s account signer.

status String Rejected or waiting Status recipient.

remark String Ini free text dari customer Free text from customer.

message String Success Message for document signing.

document_token String e478cd757de0e7527c2c7185

7cad4310 Random token generated by system.

signed_document String null Signed document’s file.

{

"info": "randomstring", "status": "rejected", "recipient": [

{

"privy_id": "AH6000", "status": "rejected",

"remark": "ini free text dari customer"

}, {

"privy_id": "AH6000", "status": "pending", "remark": null }

],

"document_token": "e478cd757de0e7527c2c71857cad4310", "signed_document": null

}

(31)

GENERAL API PRIVY

31 7. Blocked

Length reference_ number String PRVID0000000001 User’s reference number. 32

status String blocked The document has been blocked.

document_token String 10f87e83b71ef45f9bf950

baae000629 Token number for document.

unsigned_document String base64_data The document isn’t signed yet by the user.

signed_document String null The document is signed the by user.

block_reason Array Reject reason info.

code String RC20-RC24 Refer to reject reason code RC20-RC24.

message String Message RC20-RC24 Messages refer to reject reason code RC20-RC24.

reject_reason String Free text from user User can fill the reason.

recipients Object Recipient info.

privy_id String TMS2615 or DEVAN6564 User’s PrivyID.

status String Waiting or rejected Status document.

remark String null

info String Gagal validasi OTP Message info block reason. Value:

- Gagal validasi OTP.

- Gagal verifikasi tanggal lahir.

- Gagal melakukan login PrivyID .

channel_id String 001 Refer to list Channel ID. 32

{

"reference_number": "PRVID0000000001", "status": "blocked",

"document_token": "5b228a488d024b9a9a6bdf8567c7e969", "unsigned_document": "base64_data",

"signed_document": null, "block_reason": {

"code": "RC22",

"message": " Akses dokumen dibekukan karena user gagal validasi OTP"

},

"recipients": [ {

"privy_id": "tms2615", "status": "waiting", "remark": null },

{

"privy_id": "devan6564", "status": "approved", "remark": null,

"info": "Gagal validasi OTP"

} ],

"channel_id": "001", "info": ""

}

(32)

GENERAL API PRIVY

32 8. Expired Link

Length reference_ number String PRVID0000000001 User’s reference number. 32 status String link_expired The document link has expired.

document_token String 10f87e83b71ef45f9bf950

baae000629 Token number for document.

unsigned_document String base64_data The document isn’t signed yet by the user.

signed_document String null The document is signed the by user.

block_reason Array Reject reason info.

code String RC21 Refer to reject reason code RC21

message String Expired link doc signing Messages refer to reject reason code RC21

reject_reason String Free text from user User can fill the reason.

recipients Object Recipient info.

privy_id String TMS2615 or DEVAN6564 User’s PrivyID.

status String Waiting or rejected Status document.

remark String null

channel_id String 001 Refer to list Channel ID. 32

info String randomstring Additional info provides by merchant {

"reference_number": "PRVID0000000001", "status": "link_expired",

"document_token": "6a0a3ab4ef0a10fe643a6e05182d7dd9", "unsigned_document": "base64_data",

"signed_document": null, "block_reason": {

"code": "RC20",

"message": " Expired Link Doc Signing"

},

"recipients": [ {

"privy_id": "tms2615", "status": "waiting", "remark": null },

{

"privy_id": "devan6564", "status": "waiting", "remark": null }

],

"channel_id": "001", "info": ""

}

(33)

GENERAL API PRIVY

33 9. Invalid param

{

"Is Not registered"

] } ] } }

10. Invalid auth {

"401 Unauthorized"

] } }

11. Invalid signature {

] } }

(34)

GENERAL API PRIVY

34 8.2. Check Status Document Signing (Redownload Signed Document)

Development {{base_url}}/web/api/v2/doc-signing/status

Length reference_number String M PRVID0000000001 Reference number previously

channel_id String M 001 Refer to channel ID. Default using 001. 32

document_token String M e478cd757de0e7527c2c718

57cad4310 Unique identifier to represented user

generated by Privy 32

Info String O randomstring Additional info provide by merchant

{

"document_token": "e478cd757de0e7527c2c71857cad4310", "info": "randomstring",

}

Length message String Success Retrieve Data Message for document signing.

data Object [] Data information.

reference_number String PRVID0000000001 Reference number generated by

merchant. 32

channel_id String 001 Refer to list channel ID. Default using

001. 32

status String Completed or

Pending Status for document signing.

Value:

- uploaded - processing - process_emeterai - completed - rejected - blocked - link_expired - revoked

20

document_token String b4cf69de616076e9e4

87e3f44807b7fe Random token generated by system. 32 signed_document String data:file/pdf;base64,..

.. Signed document’s file.

(35)

GENERAL API PRIVY

35 1. Success document finish signing

{

"message": "Success Retrieve Data", "data": {

"status": "completed",

"document_token": "b4cf69de616076e9e487e3f44807b7fe", "signed_document": "data:file/pdf;base64,...."

} }

2. Success document pending {

"message": "Success Retrieve Data", "data": {

"status": "pending",

"document_token": "b4cf69de616076e9e487e3f44807b7fe", "signed_document": null

} }

3. Processing

data Object

[] Data information.

merchant

reference_number String PRVID0000000001 Reference number generated by merchant.

7e3f44807b7fe Random token generated by system.

status String processing The document has been signed by

some signer(s) but not completed yet (not all signers has signed the document).

message String Success Document processing status.

{

"info": "",

"document_token": "3f8a08197a2b04ed94cc9d00a961eb02", "status": "processing",

} }

(36)

GENERAL API PRIVY

36 4. Rejected

merchant

status String rejected document has been rejected by

signer.

message String RC21: User menolak

menandatangi dokumen Reject reason status.

{

"info": "",

"document_token": "2dbf5e4ce8e0e4a38f3f08288c5f5ba2", "status": "rejected",

"message": "RC21: User menolak menandatangani dokumen"

} }

5. Blocked

document_token String b4cf69de6160

76e9e487e3f44807b7fe Random token generated by system.

status String blocked The document has been blocked.

message String RC22: Akses dokumen dibekukan

karena user gagal validasi OTP Reject reason status.

(37)

GENERAL API PRIVY

37 {

"info": "",

"document_token": "f00ea330b1e4bbff12724abd464d0357", "status": "blocked",

"message": "RC22: Akses dokumen dibekukan karena user gagal validasi OTP"

} }

6. Link Expired

merchant

status String link_expired The document link has expired.

message String RC20: Expired Link Doc

Signing Reject reason status.

{

"info": "",

"document_token": "70532115f8bca6596918eabd5903fcd8", "status": "link_expired",

"message": "RC20: Expired Link Doc Signing"

} }

(38)

GENERAL API PRIVY

38 7. Revoked

merchant

document_token String b4cf69de616076e9

e487e3f44807b7fe Random token generated by system.

status String revoked The document has been voiding

by Merchant with the condition that the document has not been signed.

message String success Revoke status.

{

"info": "",

"document_token": "d6256524c1d9b754b2222d08aebbcb6f", "status": "revoked",

} }

8. Invalid auth {

"401 Unauthorized"

] } }

(39)

GENERAL API PRIVY

39 8.3. Check Document History

Development {{base_url}}/web/api/v2/doc-signing/history

Length reference_number String M PRVID0000000001 Reference number previously generated by

channel. 32

channel_id String M 001 Default using 001 32

document_token String O b4cf69de616076e9e487e

3f44807b7fe Document token

(If document token filled, then the response will return only the status of this specific document)

32

info String M randomstring Additional info provides by merchant

{

"document_token": " b4cf69de616076e9e487e3f44807b7fe"

}

Length

message String Success Retrieve Data Message for document signing.

reference_number String PRVID0000000001 Reference number from request

body 32

document Object[] Document information

document_token String b4cf69de616076e9e487… Document token

name String Document A Document name.

status String Completed document has been signed by all

signers/recipients.

signers Array of Object[] Signer info.

id String 110011

privy_id String MDR0101 Privy ID of document owner.

name String Dhimas Signer’s name

signer_type String recipient Type of signer

status String approved Status for recipient’s action

history

histories Array of Object[] Payload of signer’s history

description String Document signing for Document A Description of action history