Renew PCSID

This API is used to Renew the PCSID.

Request Method

PATCH

Request URL

{{BASE_URL}}/api/v1/onboarding/renew-pcsid

Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.

Request Headers

Parameter	Data Type	Validations and Example	Description
x-evs-auth-token	String	Required	Mandatory. User auth token.
vat	String	Required	Mandatory. VAT or Group VAT of the entity.

Request Body

Parameter	Data Type	Description
Otp	String	Mandatory. Valid Otp is required generated from the Zatca portal.
Certificate	String	Mandatory. Certificate for invoice signing
ProdbinarySecurityToken	String	Mandatory.ProdbinarySecurityToken
Prodsecret	String	Mandatory. Prodsecret

Sample Request

{
  "Otp":"502166",
  "Certificate":"LS0tLS1CRUd......",
  "ProdbinarySecurityToken":"TUlJRS9UQ0NCS09......",
  "Prodsecret":"BHJwwCMNWtyrs6wjTmF7lo6........."
}

Response Status Codes

HTTP Status Code	Description
200	For a successful renewal
400	For any kind of validation issues.
401	If the user is not authenticated for the operation.
403	If the user is not authorized for the operation.
500	HTTP Internal Server Error. Returned when the service faces internal errors.

Response Schema

Parameter	Data Type	Description
requestID	Long	Mandatory. requestID
tokenType	String	Mandatory. tokenType
dispositionMessage	String	Mandatory. Status
binarySecurityToken	String	Mandatory. binarySecurityToken
secret	String	Mandatory. secret

Sample Response

Success - HTTP Status Code - 428

{
    "requestID": 1689593602500,
    "tokenType": null,
    "dispositionMessage": "NOT_COMPLIANT",
    "binarySecurityToken": "TUlJQ0pE..........",
    "secret": "gTqHwmTubu8......."
}

Error - HTTP Status Code - 400

{
    "Status": "FAILED",
    "DeviceId": "3061A33B-4A36-48CA-B5DB-1E2983122758",
    "ErrorList": [
        {
            "ErrorCode": "Invalid-OTP",
            "ErrorMessage": "The provided OTP is invalid",
            "ErrorSource": "Zatca Error"
        }
    ]
}

Error - HTTP Status Code - 401

{
    "ErrorCode": "100401",
    "ErrorMessage": "Authentication Failed",
    "ErrorSource": "EVS_Engine"
}

Error - HTTP Status Code - 403

{
  "ErrorCode": "100403",
  "ErrorMessage": "Authorization Failed",
  "ErrorSource": "EVS_Engine"
}

Error - HTTP Status Code - 500

{
    "ErrorCode": "00500",
    "ErrorMessage": "Something Went wrong",
    "ErrorSource": "EVS_Engine"
}

API Validations

1. When PCSID has been renewed, expiry for the certificate has also been extended.

API Constraints

1. This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.

2. If the auth token is valid, but the user does not have the authorization to generate device ID, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular VAT used in the request.